Skip to content

INSTALLATION.md

Latest commit

 

History

History
667 lines (494 loc) · 14.6 KB

INSTALLATION.md

File metadata and controls

667 lines (494 loc) · 14.6 KB

Installation Guide

Complete setup instructions for the Ultimate Project System on both new and existing projects.

Table of Contents

Quick Start

One-Command Setup

# Clone the ultimate project system
git clone https://github.com/yourusername/ultimate-project.git /tmp/ultimate-project

# Run the setup script
bash /tmp/ultimate-project/scripts/init.sh \
  --agent kimi \
  --project ./my-project \
  [--existing]  # Add this for existing projects

New Projects (Greenfield)

Step 1: Initialize Project Directory

# Create your project directory
mkdir my-project
cd my-project

# Initialize git
git init

# Create initial commit
git commit --allow-empty -m "Initial commit"

Step 2: Install Ultimate Project System

Option A: Using Setup Script (Recommended)

# From outside your project directory
/path/to/ultimate-project/scripts/init.sh \
  --agent kimi \
  --project ./my-project

Option B: Manual Installation

# Copy scaffold structure
cp -r /path/to/ultimate-project/templates/scaffold/.beastmode ./
cp -r /path/to/ultimate-project/templates/scaffold/memory ./
mkdir -p .beastmode/specs src

# Copy templates
cp /path/to/ultimate-project/templates/*.md ./.beastmode/templates/

# Copy config
cp /path/to/ultimate-project/templates/scaffold/.beastmode/config.yaml ./.beastmode/

Step 3: Establish Constitution

Tell your AI agent:

/constitution Create principles for this project focused on:
- [Your domain, e.g., "web application development"]
- [Your priorities, e.g., "performance, security, scalability"]
- [Your tech preferences, e.g., "TypeScript, React, Node.js"]

This creates memory/constitution.md with the Nine Articles customized for your project.

Step 4: Configure AI Agent

Create agent-specific configuration files:

For Kimi:

Create CLAUDE.md (Kimi uses this convention):

# My Project

## Ultimate Project System

This project uses the Ultimate Project System (Beastmode × Spec-Kit synthesis).

Read `.beastmode/BEASTMODE.md` at the start of every session.

Available commands:
- /constitution - View/amend constitution
- /specify [desc] - Create feature spec
- /plan [stack] - Create implementation plan
- /tasks - Generate task list
- /implement [--parallel] - Execute implementation
- /validate - Run validation
- /release - Release feature
- /status - Show project status

See docs/ for full documentation.

Step 5: Initial Commit

git add .
git commit -m "chore: Initialize Ultimate Project System

- Add Beastmode knowledge hierarchy
- Add Spec-Kit specification structure
- Establish constitution
- Configure AI agent integration
- Add templates and documentation"

Step 6: Verify Installation

./scripts/verify.sh

Expected output:

✓ .beastmode/BEASTMODE.md exists
✓ memory/constitution.md exists
✓ .beastmode/config.yaml exists
✓ .beastmode/specs/ directory exists
✓ Templates installed
✓ Git initialized
✓ Ready for first feature

Existing Projects (Brownfield)

Step 1: Backup Your Project

cd my-existing-project
git branch backup-before-ultimate-project
git checkout -b add-ultimate-project-system

Step 2: Analyze Existing Structure

# Document current state
ls -la
find . -name "*.md" -o -name "docs" -type d

Step 3: Install Ultimate Project System

Option A: Using Setup Script

/path/to/ultimate-project/scripts/init.sh \
  --agent kimi \
  --project ./my-existing-project \
  --existing

The --existing flag:

  • Preserves existing files
  • Merges configurations
  • Adapts templates to existing structure
  • Creates migration documentation

Option B: Manual Integration

# 1. Create Beastmode structure
mkdir -p .beastmode/{context,meta,state/{design,plan,implement,validate,release},worktrees}

# 2. Create Spec-Kit structure
mkdir -p .beastmode/specs memory

# 3. Copy core files
cp /path/to/ultimate-project/templates/scaffold/.beastmode/BEASTMODE.md ./.beastmode/
cp /path/to/ultimate-project/templates/scaffold/memory/constitution.md ./memory/

# 4. Merge or create config
# If you have existing config, merge with .beastmode/config.yaml

Step 4: Extract Existing Knowledge

If your project has existing documentation, convert it:

/extract-knowledge

This command will:
1. Scan existing README, docs/, wiki/
2. Extract architectural decisions
3. Identify conventions and patterns
4. Create L2 context documents
5. Populate initial meta/learnings.md

Step 5: Create Constitution from Existing Principles

Tell your AI:

/constitution From existing codebase, extract principles for:
- Architecture patterns used
- Code organization conventions
- Testing approach
- Dependencies and tech stack

Focus on what's already working well.

Step 6: Initial Brownfield Feature

Test the system with a small enhancement:

/specify Add logging to existing authentication module
/plan Use existing tech stack
/tasks
/implement
/validate
/release

Step 7: Migrate Documentation

Gradually move existing docs to the new structure:

Old Location New Location
README.md (architecture) .beastmode/context/design/architecture.md
CONTRIBUTING.md .beastmode/context/development/conventions.md
docs/api.md .beastmode/context/design/api-design.md
Random notes .beastmode/meta/*/learnings.md

Step 8: Commit Integration

git add .
git commit -m "chore: Integrate Ultimate Project System

- Add Beastmode knowledge hierarchy
- Add Spec-Kit specification structure
- Establish constitution from existing principles
- Extract existing knowledge to context/
- Configure AI agent integration
- Add templates for new features

Migration: Existing docs preserved in docs/legacy/"

AI Agent Setup

Kimi Code CLI

Step 1: Create Kimi Skill (Recommended)

Create file: ~/.local/share/uv/tools/kimi-cli/lib/python3.13/site-packages/kimi_cli/skills/ultimate-project/SKILL.md

# Ultimate Project System

Beastmode × Spec-Kit synthesis for disciplined, specification-driven development.

## When to Use

When `.beastmode/BEASTMODE.md` exists in the project root.

## Commands

| Pattern | Command |
|---------|---------|
| "/constitution" | Establish/view constitution |
| "/specify" | Create feature specification |
| "/plan" | Create implementation plan |
| "/tasks" | Generate task list |
| "/implement" | Execute implementation |
| "/validate" | Run validation |
| "/release" | Release feature |

## Session Start

If `.beastmode/BEASTMODE.md` exists:
1. Read it silently
2. Adopt deadpan minimalist persona
3. Check for active features in .beastmode/specs/

Step 2: Project CLAUDE.md

Create in project root:

# Ultimate Project System

Read `.beastmode/BEASTMODE.md` at session start.

This project uses the unified Beastmode × Spec-Kit system.

Claude Code

Step 1: Install Beastmode Plugin

claude plugin add ultimate-project

Step 2: Create .claude/commands/

mkdir -p .claude/commands
cp /path/to/ultimate-project/templates/claude-commands/* .claude/commands/

GitHub Copilot

Step 1: VS Code Settings

Add to .vscode/settings.json:

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "This project uses the Ultimate Project System. Read .beastmode/BEASTMODE.md and follow the constitution in memory/constitution.md. Use test-first development."
    }
  ]
}

Step 2: Create .github/agents/

mkdir -p .github/agents
cp /path/to/ultimate-project/templates/copilot-commands/* .github/agents/

Cursor

Step 1: Create .cursor/rules/

mkdir -p .cursor/rules
cp /path/to/ultimate-project/templates/cursor-rules.md .cursor/rules/ultimate-project.md

Generic AI Agent

Create AGENTS.md in project root:

# AI Agent Instructions

## Ultimate Project System

This project uses a unified system combining Beastmode (disciplined workflow) 
and Spec-Kit (specification-driven development).

### On Session Start

1. Read `.beastmode/BEASTMODE.md`
2. Read `memory/constitution.md`
3. Check for active features in `.beastmode/specs/`

### Persona

Adopt deadpan minimalist voice:
- Short sentences
- Slightly annoyed at work, never at user
- Competent, understated
- Never explain jokes

### Available Commands

- `/constitution [principles]` - Establish constitution
- `/specify [description]` - Create feature spec
- `/plan [tech-stack]` - Create plan
- `/tasks` - Generate tasks
- `/implement [--parallel]` - Execute
- `/validate` - Validate
- `/release` - Release

### Workflow

Always follow: specify → plan → tasks → implement → validate → release

Run retro after each phase.

### Constitution (Nine Articles)

1. Library-First
2. CLI Interface
3. Test-First (NON-NEGOTIABLE)
4. Integration Testing
5. Observability
6. Versioning
7. Simplicity
8. Anti-Abstraction
9. Integration-First

Configuration

Core Config: .beastmode/config.yaml

system:
  name: "My Project"
  version: "0.1.0"

# Beastmode: Progressive autonomy gates
gates:
  design:
    design-approval: human        # Start supervised
    gray-area-discussion: human   # Discuss decisions
  plan:
    plan-approval: human          # Review plan
    constitution-gates: strict    # Enforce Nine Articles
  implement:
    architectural-deviation: auto # Trust after validation
    test-first-gate: strict       # NON-NEGOTIABLE
  validate:
    validation-failure: human     # Handle failures
  retro:
    context-write: human          # Review context updates
    learnings: auto               # Auto-capture learnings
    sops: human                   # Review new SOPs
  release:
    version-confirmation: auto    # Auto-detect semver
    beastmode-md-approval: human  # Review L0 changes

# Spec-Kit: Constitutional enforcement
constitution:
  path: "memory/constitution.md"
  enforce_gates: true
  articles:
    library_first: strict
    cli_interface: strict
    test_first: strict          # NON-NEGOTIABLE
    integration_testing: warn   # Warn but allow
    observability: strict
    versioning: strict
    simplicity: strict
    anti_abstraction: strict
    integration_first: strict

# Beastmode: Swarm mode
swarm:
  enabled: true
  max_parallel: 5
  file_isolation_check: true
  
  research:
    max_parallel: 5
    parallel_topics: true
  
  implement:
    max_parallel: 3
    parallel_waves: true
    verification_required: true
  
  retro:
    max_parallel: 2
    parallel_walkers: true

# Spec-Kit: Feature organization
features:
  numbering: sequential          # 001, 002, 003...
  directory: ".beastmode/specs/"
  templates: ".beastmode/templates/"
  
  # Auto-numbering options
  auto_number:
    enabled: true
    prefix_format: "{number:03d}-{short_name}"
    start_from: 1

# Workflow transitions
transitions:
  specify-to-plan: auto          # Auto-advance if spec clean
  plan-to-tasks: auto            # Auto-generate tasks
  tasks-to-implement: human      # Confirm before coding
  implement-to-validate: auto    # Auto-validate after impl
  validate-to-release: human     # Human approval to ship

# Context management
context:
  threshold: 20                  # % remaining for auto-advance
  auto_load_l1: true             # Auto-load phase context
  compression_strategy: summary  # How to handle large context

# Logging
logging:
  level: info                    # debug, info, warn, error
  retro_summaries: true          # Log retro findings
  gate_decisions: true           # Log gate resolutions

Verification

Automated Verification

./scripts/verify.sh

Checks:

  • ✅ Directory structure exists
  • ✅ Core files present
  • ✅ Config valid
  • ✅ Templates installed
  • ✅ Git initialized
  • ✅ Constitution established
  • ✅ AI agent configured

Manual Verification Checklist

Structure:

  • .beastmode/BEASTMODE.md exists
  • .beastmode/config.yaml exists
  • .beastmode/context/ directory exists
  • .beastmode/meta/ directory exists
  • .beastmode/state/ directory exists
  • memory/constitution.md exists
  • .beastmode/specs/ directory exists

Configuration:

  • Config YAML is valid
  • Gates configured appropriately
  • Swarm mode enabled (if desired)
  • Constitution path correct

AI Integration:

  • Agent can read BEASTMODE.md
  • Commands recognized
  • Persona adopted

Test Run:

  • /constitution works
  • /specify test-feature works
  • Files created in correct locations

Troubleshooting

Issue: AI doesn't recognize commands

Solution:

  1. Check AI-specific setup (see AI Agent Setup)
  2. Ensure project root has marker file (BEASTMODE.md)
  3. Tell AI explicitly: "This project uses Ultimate Project System"

Issue: Constitution gates blocking everything

Solution: Adjust strictness in .beastmode/config.yaml:

constitution:
  articles:
    test_first: warn      # Change from strict

Or document justified exceptions in plan.

Issue: Swarm mode causing conflicts

Solution:

  1. Disable for problematic phases:
swarm:
  implement:
    parallel_waves: false
  1. Or increase verification:
swarm:
  file_isolation_check: strict  # Fail on any overlap

Issue: Retro not promoting knowledge

Solution:

  1. Check gate settings:
gates:
  retro:
    context-write: auto  # Change from human
  1. Manually run retro:
/retro phase=design feature=001-feature

Issue: Existing project conflicts

Solution: Use --existing flag with init script, or manually:

  1. Backup first: git branch backup
  2. Install to subdirectory first: mkdir .ultimate-project && cp ...
  3. Gradually move files
  4. Merge configurations carefully

Issue: Feature numbering conflicts

Solution: Reset numbering in config:

features:
  auto_number:
    start_from: 100  # Start from higher number

Or manually assign:

/specify --number 042 my-feature

Next Steps

After installation:

  1. Read the docs - Start with ARCHITECTURE.md
  2. Try an example - See examples/
  3. Create first feature - Run /specify on a small feature
  4. Iterate - Adjust configuration based on experience

Installation Guide Version: 1.0
License: Apache 2.0
Part of: Ultimate Project System Documentation