This document synthesizes Beastmode (disciplined engineering workflow with persistent context) and Spec-Kit (Spec-Driven Development with constitutional governance) into a unified system for project creation and management.
A system where:
- Specifications are executable (Spec-Kit philosophy)
- Knowledge compounds across sessions (Beastmode philosophy)
- Architecture is governed by immutable principles (Constitution)
- Workflow is disciplined and phase-driven (5-phase cycle)
- AI agents collaborate in swarms (parallel execution)
- Projects self-document and self-improve (retro loop)
Core Strengths:
-
Progressive Knowledge Hierarchy (L0-L3)
- L0: System manual (persona, workflow) - autoloaded
- L1: Phase summaries - loaded at prime
- L2: Detail docs - loaded on-demand
- L3: State artifacts - checkpoint history
-
Five-Phase Workflow
design → plan → implement → validate → releaseEach phase: prime → execute → validate → checkpoint
-
Retro System
- Context reconciliation (L3 → L2 → L1)
- Meta learning capture (SOPs, overrides, learnings)
- L0 promotion via release
-
Write Protection
- Phases write only to
state/ - Retro is sole gatekeeper for context/meta
- Prevents corruption of published knowledge
- Phases write only to
-
Gate System
- Hard gates (unconditional constraints)
- Configurable gates (human/auto modes)
- Progressive autonomy
-
Git Worktree Isolation
- Feature branches with worktrees
- Squash-per-release commits
- Clean separation of concerns
Gaps:
- No formal specification structure
- No architectural constitution
- Limited template-driven quality
- No research phase
Core Strengths:
-
Spec-Driven Development (SDD)
- Specifications as primary artifacts
- Code serves specifications
- Executable specifications generate implementation
-
Constitutional Governance
- Nine Articles of Development
- Immutable architectural principles
- Gates enforce constitution
- Article III: Test-First (NON-NEGOTIABLE)
-
Template-Driven Quality
- Feature specification template
- Implementation plan template
- Forces explicit uncertainty markers [NEEDS CLARIFICATION]
- Checklists act as "unit tests" for specifications
-
Command Structure
/speckit.constitution → Establish principles /speckit.specify → Create feature spec /speckit.plan → Create implementation plan /speckit.tasks → Generate task list /speckit.implement → Execute implementation -
Research-Driven Context
- Phase 0: Research unknowns
- Research agents gather technical context
- Best practices investigation
-
Feature Organization
- Numbered features (001-, 002-)
- .beastmode/specs/[feature]/ directory structure
- Branch per feature
Gaps:
- No persistent knowledge hierarchy across features
- No retro/learning system
- Limited gate configurability
- No validation/release phases
- No swarm mode for parallel execution
┌─────────────────────────────────────────────────────────────────┐
│ PROJECT CREATION LIFECYCLE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 0. FOUNDATION │
│ └── /constitution establish │
│ └── memory/constitution.md │
│ │
│ 1. SPECIFICATION │
│ └── /specify [feature-description] │
│ ├── .beastmode/specs/NNN-[feature]/spec.md │
│ └── [Beastmode: design phase] │
│ │
│ 2. RESEARCH │
│ └── /research (auto-triggered by clarify markers) │
│ └── .beastmode/specs/NNN-[feature]/research.md │
│ │
│ 3. PLANNING │
│ └── /plan [tech-stack] │
│ ├── .beastmode/specs/NNN-[feature]/plan.md │
│ ├── .beastmode/specs/NNN-[feature]/data-model.md │
│ ├── .beastmode/specs/NNN-[feature]/contracts/ │
│ └── [Beastmode: plan phase] │
│ │
│ 4. TASK GENERATION │
│ └── /tasks │
│ ├── .beastmode/specs/NNN-[feature]/tasks.md │
│ └── .beastmode/state/plan/NNN-[feature].tasks.json │
│ │
│ 5. IMPLEMENTATION │
│ └── /implement [--parallel] │
│ ├── [Beastmode: implement phase with swarm] │
│ └── .beastmode/worktrees/NNN-[feature]/ │
│ │
│ 6. VALIDATION │
│ └── /validate │
│ ├── .beastmode/specs/NNN-[feature]/validation.md │
│ └── [Beastmode: validate phase] │
│ │
│ 7. RELEASE │
│ └── /release │
│ ├── [Beastmode: release phase] │
│ └── Archive .beastmode/specs/ to .beastmode/state/release/ │
│ │
│ 8. RETRO (runs after each phase) │
│ └── Context reconciliation + Meta learning │
│ └── Updates .beastmode/context/ and .beastmode/meta/ │
│ │
└─────────────────────────────────────────────────────────────────┘
project/
├── .beastmode/ # Beastmode: Knowledge & workflow
│ ├── BEASTMODE.md # L0: System manual (persona, workflow)
│ ├── config.yaml # Gates, swarm settings
│ ├── context/ # L1-L2: Published knowledge
│ │ ├── DESIGN.md # L1: Design conventions
│ │ ├── PLAN.md # L1: Plan conventions
│ │ ├── IMPLEMENT.md # L1: Implementation patterns
│ │ ├── VALIDATE.md # L1: Validation standards
│ │ ├── RELEASE.md # L1: Release process
│ │ └── design/ # L2: Design details
│ │ └── architecture.md
│ ├── meta/ # L1-L2: Learnings & SOPs
│ │ ├── DESIGN.md
│ │ └── design/
│ │ ├── sops.md # Standard procedures
│ │ ├── overrides.md # Project rules
│ │ └── learnings.md # Session insights
│ ├── state/ # L3: Checkpoint artifacts
│ │ ├── design/
│ │ ├── plan/
│ │ ├── implement/
│ │ ├── validate/
│ │ └── release/
│ └── worktrees/ # Git worktrees
│ └── NNN-feature/
│
├── memory/ # Spec-Kit: Project memory
│ ├── constitution.md # Nine Articles
│ ├── guidance.md # Runtime guidance
│ └── principles/ # Additional principles
│
├── .beastmode/specs/ # Spec-Kit: Feature specs
│ └── NNN-feature-name/ # Numbered feature directories
│ ├── spec.md # Feature specification
│ ├── research.md # Research findings
│ ├── plan.md # Implementation plan
│ ├── data-model.md # Data models
│ ├── contracts/ # API contracts
│ ├── tasks.md # Task list
│ ├── quickstart.md # Validation scenarios
│ └── validation.md # Validation report
│
└── src/ # Implementation
└── [actual code]
Spec-Kit Artifacts → Beastmode Hierarchy
.beastmode/specs/NNN-feature/spec.md
↓ [retro after design phase]
.beastmode/state/design/NNN-feature.md
↓ [context walker analyzes]
.beastmode/context/design/[domain].md (L2)
↓ [L2 summary propagates]
.beastmode/context/DESIGN.md (L1)
↓ [release rolls up]
.beastmode/BEASTMODE.md (L0)
Meta Learning Flow:
.beastmode/specs/NNN-feature/insights/
↓ [meta walker captures]
.beastmode/meta/design/learnings.md
↓ [3+ occurrences]
.beastmode/meta/design/sops.md
The Spec-Kit Constitution becomes an extension of Beastmode's L0:
# .beastmode/BEASTMODE.md
## Beastmode × Spec-Kit Unified System
### Persona
[Beastmode persona]
### Workflow
[5-phase workflow]
### Constitution (Spec-Kit)
Immutable architectural principles:
#### Article I: Library-First
Every feature begins as a standalone library.
#### Article II: CLI Interface
All libraries expose functionality via CLI.
#### Article III: Test-First (NON-NEGOTIABLE)
TDD mandatory. Tests → Approval → Fail → Implement.
[Articles IV-IX...]
### Knowledge Hierarchy
[L0-L3 structure]Beastmode Design Phase enhanced with Spec-Kit templates:
-
Prime
- Load context/DESIGN.md
- Load memory/constitution.md
- Check for existing specs
-
Execute
- Parse feature description
- Generate feature number
- Create .beastmode/specs/NNN-feature/spec.md from template
- Identify [NEEDS CLARIFICATION] markers
- Auto-trigger /research for unknowns
- Fill template sections:
- User Scenarios (prioritized P1, P2, P3)
- Requirements (FR-001, FR-002...)
- Key Entities
- Edge Cases
-
Validate
- Checklist validation:
- No [NEEDS CLARIFICATION] remain
- User stories independently testable
- Acceptance criteria measurable
- Constitution compliance check
- Checklist validation:
-
Checkpoint
- Save to .beastmode/specs/NNN-feature/spec.md
- Save to .beastmode/state/design/
- Run retro (context + meta)
Beastmode Plan Phase with Spec-Kit planning:
-
Prime
- Load spec.md
- Load constitution
- Load plan template
-
Execute
- Phase -1: Gates
- Simplicity Gate (≤3 projects?)
- Anti-Abstraction Gate (framework directly?)
- Integration-First Gate (contracts defined?)
- Phase 0: Research (if needed)
- Phase 1: Design
- Create data-model.md
- Create contracts/
- Create quickstart.md
- Phase 2: Planning
- Technical architecture
- Implementation phases
- Testing strategy
- Phase -1: Gates
-
Validate
- Design coverage check
- Constitution compliance
- Plan approval gate
-
Checkpoint
- Save plan.md
- Run retro
Beastmode Implement Phase with Spec-Kit task generation:
-
Prime
- Load plan.md
- Parse contracts
- /tasks generates task list
-
Execute
- Convert tasks.md to Beastmode format
- Wave-based execution
- Swarm mode: Parallel-safe waves
- Spec checks after each task
- Deviation tracking
-
Validate
- Run tests
- Check constitution compliance
-
Checkpoint
- Save deviations
- Run retro
Beastmode Validate Phase:
-
Prime
- Load quickstart.md scenarios
- Load validation criteria
-
Execute
- Run acceptance scenarios
- Run quality gates
- Constitution final check
-
Checkpoint
- Save validation.md
- Run retro
Beastmode Release Phase:
-
Prime
- Load all artifacts
- Determine version bump
-
Execute
- Generate changelog
- Archive .beastmode/specs/ to .beastmode/state/release/
- Squash merge
- Tag release
-
Checkpoint
- Update L0 if needed
- Final retro
| Intent | Beastmode | Spec-Kit | Unified |
|---|---|---|---|
| Establish principles | - | /constitution | /constitution |
| Create feature spec | /design | /specify | /specify (enhanced) |
| Research unknowns | (implicit) | (implicit) | /research (explicit) |
| Create plan | /plan | /plan | /plan (with gates) |
| Generate tasks | (manual) | /tasks | /tasks (auto) |
| Implement | /implement | /implement | /implement [--parallel] |
| Validate | /validate | - | /validate |
| Release | /release | - | /release |
| Status | /status | - | /status |
/constitution → Establishes memory/constitution.md
↓
/specify [desc] → specs/NNN-feature/spec.md
↓
/clarify → Resolves [NEEDS CLARIFICATION]
↓
/research → specs/NNN-feature/research.md
↓
/plan [stack] → plan.md + data-model.md + contracts/
↓
/tasks → tasks.md + .tasks.json
↓
/implement → Code in worktree
↓
/validate → validation.md
↓
/release → Merged to main, tagged
Combines Spec-Kit structure with Beastmode metadata:
# Feature Specification: [FEATURE NAME]
**Feature Number**: NNN
**Feature Branch**: `NNN-feature-name`
**Beastmode State**: `.beastmode/state/design/NNN-feature.md`
**Status**: Draft → Specified → Planned → Implemented → Released
**Created**: [DATE]
## User Scenarios & Testing
### User Story 1 - [Title] (Priority: P1)
[Description]
**Why this priority**: [Value proposition]
**Independent Test**: [How to test standalone]
**Acceptance Scenarios**:
1. **Given** [state], **When** [action], **Then** [outcome]
## Requirements
### Functional Requirements
- **FR-001**: System MUST [capability]
- **FR-002**: [NEEDS CLARIFICATION: ...]
### Non-Functional Requirements
- **NFR-001**: Performance [criteria]
## Edge Cases
- What happens when [condition]?
## Beastmode Metadata
### Gray Areas Discussed
1. [Decision area] → [Decision made]
### Deferred Ideas
- [Idea] (out of scope for now)
### Retro Notes
- [Learnings from design phase]# Implementation Plan: [FEATURE NAME]
**Feature Number**: NNN
**Spec Reference**: .beastmode/specs/NNN-feature/spec.md
**Constitution**: memory/constitution.md
## Phase -1: Pre-Implementation Gates
### Simplicity Gate (Article VII)
- [ ] Using ≤3 projects?
- [ ] No future-proofing?
### Anti-Abstraction Gate (Article VIII)
- [ ] Using framework directly?
- [ ] Single model representation?
### Integration-First Gate (Article IX)
- [ ] Contracts defined?
- [ ] Contract tests written?
## Phase 0: Research
[Links to research.md]
## Phase 1: Design
### Data Model
[Reference to data-model.md]
### Contracts
[Reference to contracts/]
## Phase 2: Implementation
### Wave 1: [Name]
**Parallel-safe**: Yes/No
#### Task 1: [Name]
**Files**: [paths]
**Steps**: [numbered steps]
**Verification**: [command]
### Wave 2: [Name]
...
## Beastmode Integration
### Waves Mapped
- Wave 1 → .tasks.json waves[1]
- Wave 2 → .tasks.json waves[2]
### Gates
- plan-approval: [config setting]# Triggered by [NEEDS CLARIFICATION] markers
clarifications = extract_clarifications(spec.md)
research_tasks = []
for item in clarifications:
task = Task(
subagent_name="researcher",
prompt=f"Research: {item.question}\nContext: {feature_context}",
description=f"Research {item.topic}"
)
research_tasks.append(task)
# Parallel execution
findings = [t.result() for t in research_tasks]
research_md = consolidate_findings(findings)# From tasks.md, group by wave
waves = parse_waves(tasks.md)
for wave in waves:
if wave.parallel_safe:
# Verify file isolation
all_files = [f for t in wave.tasks for f in t.files]
if len(all_files) == len(set(all_files)):
# Spawn parallel agents
agents = [Task(subagent_name="implementer", prompt=...)
for task in wave.tasks]
results = [a.result() for a in agents]
else:
# Sequential fallback
results = [implement_sequential(t) for t in wave.tasks]# After each phase
context_task = Task(
subagent_name="retro-context",
prompt=f"Review {artifact} against context docs"
)
meta_task = Task(
subagent_name="retro-meta",
prompt=f"Capture learnings from {phase}"
)
# Wait for both
context_result = context_task.result()
meta_result = meta_task.result()# .beastmode/config.yaml
system:
name: "Beastmode × Spec-Kit"
version: "2.0.0"
# Beastmode: Gates
gates:
design:
design-approval: human
plan:
plan-approval: human
constitution-gates: strict # NEW: Enforce Article gates
implement:
architectural-deviation: auto
test-first-gate: strict # NEW: Enforce Article III
validate:
validation-failure: human
retro:
context-write: human
learnings: human
sops: human
release:
version-confirmation: auto
# Spec-Kit: Constitutional Enforcement
constitution:
path: "memory/constitution.md"
enforce_gates: true
articles:
- library_first # Article I
- cli_interface # Article II
- test_first # Article III (strict)
- integration_testing # Article IV
- observability # Article V
- versioning # Article VI
- simplicity # Article VII
- anti_abstraction # Article VIII
- integration_first # Article IX
# Beastmode: Swarm Mode
swarm:
enabled: true
max_parallel: 5
file_isolation_check: true
# Phase-specific
research:
parallel_topics: true
implement:
parallel_waves: true
retro:
parallel_walkers: true
# Spec-Kit: Feature Organization
features:
numbering: sequential
directory: ".beastmode/specs/"
templates: ".beastmode/templates/"
# Transitions
transitions:
specify-to-plan: auto
plan-to-tasks: auto
tasks-to-implement: human
implement-to-validate: auto
validate-to-release: human
context_threshold: 20- Template discipline: Spec-Kit templates constrain LLM output
- Uncertainty markers: [NEEDS CLARIFICATION] prevents assumptions
- Constitutional gates: Architecture enforced from start
- Research integration: Unknowns resolved before implementation
- L0-L3 hierarchy: Knowledge survives sessions
- Retro loop: System learns from every phase
- Context promotion: Insights bubble up to L0
- Feature archive: Complete history preserved
- 5-phase workflow: No skipping steps
- Write protection: Phases can't corrupt knowledge
- Gate system: Progressive autonomy
- Swarm mode: Parallel efficiency
- Constitution: Immutable principles
- Numbered features: Clear organization
- Worktree isolation: Clean separation
- Validation gates: Quality enforced
- Set up
.beastmode/structure - Create unified BEASTMODE.md
- Port Spec-Kit constitution
- Configure gates
- Adapt spec-template.md
- Adapt plan-template.md
- Create unified task format
- Test template generation
- Implement /constitution
- Implement /specify
- Implement /plan
- Implement /tasks
- Implement parallel research
- Implement parallel waves
- Implement parallel retro
- Test file isolation
- Integrate Beastmode phases
- Connect retro system
- Test full workflow
- Documentation
The synthesis of Beastmode and Spec-Kit creates a system that:
- Thinks in specifications (Spec-Kit) while learning from execution (Beastmode)
- Enforces architecture (Constitution) while adapting to reality (Retro)
- Generates quality specs (Templates) while persisting knowledge (Hierarchy)
- Works in phases (Workflow) while executing in parallel (Swarm)
This is the ultimate project creation system: disciplined yet flexible, prescriptive yet learning, structured yet efficient.
Version: 1.0.0
License: Apache 2.0
Sources:
- Beastmode: https://github.com/BugRoger/beastmode
- Spec-Kit: https://github.com/github/spec-kit