Ultimate Project System

Beastmode × Spec-Kit Synthesis: The definitive project creation and management system combining disciplined engineering workflow with specification-driven development.

┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│   SPECIFY → PLAN → TASKS → IMPLEMENT → VALIDATE → RELEASE                   │
│      │        │       │         │          │         │                      │
│      ▼        ▼       ▼         ▼          ▼         ▼                      │
│   ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐  ┌──────┐  ┌──────┐                  │
│   │ Spec │ │ Plan │ │Tasks │ │ Code │  │ Test │  │ Ship │                  │
│   │  .md │ │  .md │ │ .md  │ │      │  │      │  │      │                  │
│   └──────┘ └──────┘ └──────┘ └──────┘  └──────┘  └──────┘                  │
│                                                                             │
│   With: Constitution • Knowledge Hierarchy • Swarm Mode • Retro Loop        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

🎯 What Is This?

The Ultimate Project System unifies two powerful methodologies:

Beastmode	Spec-Kit	Ultimate System
Disciplined 5-phase workflow	Spec-Driven Development	Executable specs with workflow discipline
L0-L3 knowledge hierarchy	Feature specifications	Persistent specs that compound knowledge
Retro learning loop	Constitutional governance	Self-improving system with immutable principles
Swarm mode (parallel agents)	Research agents	Parallel execution with research context
Progressive autonomy gates	Phase gates	Progressive autonomy with constitutional enforcement

The Result

A system where:

✅ Specifications are executable - they generate implementation
✅ Knowledge persists - across sessions, features, and team members
✅ Architecture is governed - by immutable constitutional principles
✅ Workflow is disciplined - no skipping phases, retro after each
✅ Execution is efficient - parallel swarm mode where safe
✅ Projects self-improve - retro loop captures and promotes learnings

🚀 Quick Start

For New Projects

# 1. Clone this repository
# This is a synthesis of two existing projects:
# - Beastmode: https://github.com/BugRoger/beastmode
# - Spec-Kit: https://github.com/github/spec-kit
#
# To use this system, you can either:
# 1. Copy the files directly from this repository
# 2. Create your own synthesis based on the upstream projects
#
# For the original projects, visit:
git clone https://github.com/github/spec-kit.git
# or
git clone https://github.com/BugRoger/beastmode.git
cd ultimate-project

# 2. Run the setup script for your AI agent
./scripts/init.sh --agent kimi --project ../my-new-project

# 3. Follow the guided setup
cd ../my-new-project
# Then tell your AI: /constitution establish

For Existing Projects

# 1. Clone this repository
git clone https://github.com/yourusername/ultimate-project.git
cd ultimate-project

# 2. Run the migration script
./scripts/init.sh --agent kimi --project ../my-existing-project --existing

# 3. Review and commit the changes
cd ../my-existing-project
git add .
git commit -m "chore: Add Ultimate Project System"

Manual Setup

See docs/INSTALLATION.md for detailed manual setup instructions.

📁 Project Structure

ultimate-project/                 # This repository
├── README.md                     # This file
├── docs/                         # Comprehensive documentation
│   ├── ARCHITECTURE.md           # System architecture deep dive
│   ├── COMMANDS.md               # Command reference
│   ├── INSTALLATION.md           # Setup for new/existing projects
│   ├── CONSTITUTION.md           # The Nine Articles explained
│   ├── SWARM_MODE.md             # Parallel execution guide
│   └── VISUAL_GUIDE.md           # Diagrams and flowcharts
├── templates/                    # Specification templates
│   ├── spec-template.md          # Feature specification
│   ├── plan-template.md          # Implementation plan
│   └── tasks-template.md         # Task list
├── scripts/                      # Setup and utility scripts
│   ├── init.sh                   # Project initialization
│   ├── install-kimi.sh           # Kimi-specific setup
│   └── verify.sh                 # Verify installation
├── examples/                     # Example projects
│   ├── new-project/              # Greenfield example
│   └── existing-project/         # Brownfield example
└── src/                          # System source (if needed)

When you initialize a project, it gets this structure:

your-project/
├── .beastmode/                   # Beastmode: Knowledge & workflow
│   ├── BEASTMODE.md              # L0: System manual
│   ├── config.yaml               # Configuration
│   ├── context/                  # L1-L2: Published knowledge
│   ├── meta/                     # L1-L2: Learnings & SOPs
│   ├── state/                    # L3: Checkpoint artifacts
│   └── worktrees/                # Git worktrees
├── memory/                       # Spec-Kit: Project memory
│   ├── constitution.md           # The Nine Articles
│   └── guidance.md               # Runtime guidance
├── .beastmode/specs/             # Spec-Kit: Feature specs
│   └── NNN-feature/              # Numbered features
│       ├── spec.md
│       ├── plan.md
│       ├── tasks.md
│       └── ...
└── src/                          # Implementation

🎓 Core Concepts

The Nine Articles (Constitution)

Immutable architectural principles:

Library-First - Every feature begins as a standalone library
CLI Interface - All libraries expose functionality via CLI
Test-First - TDD mandatory - tests before implementation
Integration Testing - Real dependencies over mocks
Observability - Everything inspectable through text I/O
Versioning - Semantic versioning
Simplicity - ≤3 projects, YAGNI principles
Anti-Abstraction - Use frameworks directly
Integration-First - Contract tests before implementation

Knowledge Hierarchy (L0-L3)

Level	Path	Content	When Loaded
L0	`.beastmode/BEASTMODE.md`	System manual, constitution	Autoload every session
L1	`.beastmode/context/{PHASE}.md`	Phase summaries	At phase start
L2	`.beastmode/context/{phase}/{domain}.md`	Detail docs	On-demand
L3	`.beastmode/specs/NNN-*/`, `.beastmode/state/`	Specs, artifacts	Checkpoint

The Workflow

specify → plan → tasks → implement → validate → release
   │        │       │         │          │         │
   └────────┴───────┴─────────┴──────────┴─────────┘
                         │
                    [RETRO after each]
                         │
                         ▼
              Knowledge promotion (L3→L2→L1→L0)

Each phase: prime → execute → validate → checkpoint → retro

🐝 Swarm Mode

Parallel execution using AI agent Task spawning:

# Research multiple topics in parallel
research_tasks = [
    Task(agent="researcher", topic="JWT auth"),
    Task(agent="researcher", topic="Session cookies"),
    Task(agent="researcher", topic="OAuth2")
]
findings = [t.result() for t in research_tasks]

# Execute parallel-safe waves
if wave.parallel_safe and no_file_overlap(tasks):
    agents = [Task(agent="implementer", task=t) for t in tasks]
    results = [a.result() for a in agents]

# Run retro agents simultaneously
context_task = Task(agent="retro-context", ...)
meta_task = Task(agent="retro-meta", ...)
results = [context_task.result(), meta_task.result()]

📖 Documentation

Document	Description
docs/ARCHITECTURE.md	Deep dive into unified architecture
docs/INSTALLATION.md	Setup for new and existing projects
docs/COMMANDS.md	Complete command reference
docs/CONSTITUTION.md	The Nine Articles explained
docs/SWARM_MODE.md	Parallel execution patterns
docs/VISUAL_GUIDE.md	Diagrams and flowcharts

🛠️ Commands

Specification Commands

Command	Description
`/constitution [principles]`	Establish project constitution
`/specify [description]`	Create feature specification
`/research [topics]`	Research technical unknowns

Planning Commands

Command	Description
`/plan [tech-stack]`	Create implementation plan
`/tasks`	Generate task list

Execution Commands

Command	Description
`/implement [--parallel]`	Execute implementation
`/validate`	Run validation
`/release`	Release feature
`/status`	Show project status

🌟 Why This System?

Compared to Traditional Development

Aspect	Traditional	Ultimate System
Spec to Code	Manual translation	Executable generation
Knowledge	Lost between sessions	Persistent L0-L3 hierarchy
Architecture	Ad-hoc decisions	Constitution-governed
Parallel Work	Risky, uncoordinated	Safe swarm mode
Learning	Individual, lost	Captured in retro, promoted
Time to MVP	Days	Hours

Real-World Example

Building a User Authentication System:

Traditional Approach:
├─ Write PRD (4 hours)
├─ Technical design (4 hours)
├─ Implementation (16 hours)
├─ Testing (8 hours)
└─ Total: 4 days

Ultimate System:
├─ /specify (5 min)
├─ /plan (10 min)
├─ /tasks (2 min)
├─ /implement --parallel (45 min)
├─ /validate (5 min)
└─ Total: 72 minutes

With better quality (constitution-enforced, test-first, documented).

🤝 Supported AI Agents

Agent	Support	Notes
Kimi Code CLI	✅ Full	Native Task tool support
Claude Code	✅ Full	Via beastmode-claude bridge
GitHub Copilot	✅ Full	Via VS Code extension
Cursor	✅ Full	Via cursor rules
Windsurf	✅ Full	Via workflows
Generic	⚡ Partial	Bring your own adapter

📦 Installation

Prerequisites

Git 2.30+
Python 3.11+ (for utilities)
An AI agent (Kimi, Claude, Copilot, etc.)

Quick Install

git clone https://github.com/yourusername/ultimate-project.git
cd ultimate-project
./scripts/init.sh --agent kimi --project ../my-project

See docs/INSTALLATION.md for detailed options.

🎓 Learning Path

Beginner

Read docs/CONSTITUTION.md - Understand the Nine Articles
Try the examples/new-project/ example
Run through a simple feature end-to-end

Intermediate

Read docs/ARCHITECTURE.md - Understand the synthesis
Customize templates in templates/
Configure gates in .beastmode/config.yaml
Experiment with swarm mode

Advanced

Read docs/SWARM_MODE.md - Master parallel execution
Implement custom retro agents
Extend the constitution for your domain
Contribute back to the project

📝 License

Apache 2.0 - See LICENSE

🙏 Credits

Beastmode: https://github.com/BugRoger/beastmode - Disciplined engineering workflow system
Spec-Kit: https://github.com/github/spec-kit - Spec-Driven Development toolkit
Contributors: The community that shaped both systems

💬 Support

Version: 1.0.0
Last Updated: 2026-03-08
Status: Production Ready

"The ultimate project creation system: disciplined yet flexible, prescriptive yet learning, structured yet efficient."

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.beastmode		.beastmode
docs		docs
examples		examples
memory		memory
scripts		scripts
templates		templates
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Ultimate Project System

🎯 What Is This?

The Result

🚀 Quick Start

For New Projects

For Existing Projects

Manual Setup

📁 Project Structure

🎓 Core Concepts

The Nine Articles (Constitution)

Knowledge Hierarchy (L0-L3)

The Workflow

🐝 Swarm Mode

📖 Documentation

🛠️ Commands

Specification Commands

Planning Commands

Execution Commands

🌟 Why This System?

Compared to Traditional Development

Real-World Example

🤝 Supported AI Agents

📦 Installation

Prerequisites

Quick Install

🎓 Learning Path

Beginner

Intermediate

Advanced

📝 License

🙏 Credits

💬 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages