basicmachines-co-basic-memory/specs/SPEC-1 Specification-Driven Development Process.md

title, type, permalink, tags

title	type	permalink	tags
SPEC-1: Specification-Driven Development Process	spec	specs/spec-1-specification-driven-development-process	process specification development meta

SPEC-1: Specification-Driven Development Process

Why

We're implementing specification-driven development to solve the complexity and circular refactoring issues in our web development process. Instead of getting lost in framework details and type gymnastics, we start with clear specifications that drive implementation.

The default approach of adhoc development with AI agents tends to result in:

• Circular refactoring cycles
• Fighting framework complexity
• Lost context between sessions
• Unclear requirements and scope

What

This spec defines our process for using basic-memory as the specification engine to build basic-memory-cloud. We're creating a recursive development pattern where basic-memory manages the specs that drive the development of basic-memory-cloud.

Affected Areas:

• All future component development
• Architecture decisions
• Agent collaboration workflows
• Knowledge management and context preservation

How (High Level)

Specification Structure

Name: Spec names should be numbered sequentially, followed by a description eg. SPEC-X - Simple Description.md. See: Spec-2: Slash Commands Reference

Every spec is a complete thought containing:

• Why: The reasoning and problem being solved
• What: What is affected or changed
• How: High-level approach to implementation
• How to Evaluate: Testing/validation procedure
• Additional context as needed

Living Specification Format

Specifications are living documents that evolve throughout implementation:

Progress Tracking:

• Completed items: Use ✅ checkmark emoji for implemented features
• Pending items: Use - [ ] GitHub-style checkboxes for remaining tasks
• In-progress items: Use - [x] when work is actively underway

Status Philosophy:

• Avoid static status headers like "COMPLETE" or "IN PROGRESS" that become stale
• Use checklists within content to show granular implementation progress
• Keep specs informative while providing clear progress visibility
• Update continuously as understanding and implementation evolve

Example Format:

### ComponentName
- ✅ Basic functionality implemented
- ✅ Props and events defined
- - [ ] Add sorting controls
- - [ ] Improve accessibility
- - [x] Currently implementing responsive design

This creates git-friendly progress tracking where [ ] easily becomes [x] or ✅ when completed, and specs remain valuable throughout the development lifecycle.

Claude Code

We will leverage Claude Code capabilities to make the process semi-automated.

• Slash commands: define repeatable steps in the process (create spec, implement, review, etc)
• Agents: define roles to carry out instructions (front end developer, baskend developer, etc)
• MCP tools: enable agents to implement specs via actions (write code, test, etc)

Workflow

1. Create: Write spec as complete thought in /specs folder
2. Discuss: Iterate and refine through agent collaboration
3. Implement: Hand spec to appropriate specialist agent
4. Validate: Review implementation against spec criteria
5. Document: Update spec with learnings and decisions

Slash Commands

Claude slash commands are used to manage the flow. These are simple instructions to help make the process uniform. They can be updated and refined as needed.

• /spec create [name] - Create new specification
• /spec status - Show current spec states
• /spec implement [name] - Hand to appropriate agent
• /spec review [name] - Validate implementation

Agent Orchestration

Agents are defined with clear roles, for instance:

• system-architect: Creates high-level specs, ADRs, architectural decisions
• vue-developer: Component specs, UI patterns, frontend architecture
• python-developer: Implementation specs, technical details, backend logic
• Each agent reads/updates specs through basic-memory tools.

How to Evaluate

Success Criteria

• Specs provide clear, actionable guidance for implementation
• Reduced circular refactoring and scope creep
• Persistent context across development sessions
• Clean separation between "what/why" and implementation details
• Specs record a history of what happened and why for historical context

Testing Procedure

1. Create a spec for an existing problematic component
2. Have an agent implement following only the spec
3. Compare result quality and development speed vs. ad-hoc approach
4. Measure context preservation across sessions
5. Evaluate spec clarity and completeness

Metrics

• Time from spec to working implementation
• Number of refactoring cycles required
• Agent understanding of requirements
• Spec reusability for similar components

Notes

• Start simple: specs are just complete thoughts, not heavy processes
• Use basic-memory's knowledge graph to link specs, decisions, components
• Let the process evolve naturally based on what works
• Focus on solving the actual problem: Manage complexity in development

Observations

• [problem] Web development without clear goals and documentation circular refactoring cycles #complexity
• [solution] Specification-driven development reduces scope creep and context loss #process-improvement
• [pattern] basic-memory as specification engine creates recursive development loop #meta-development
• [workflow] Five-step process: Create → Discuss → Implement → Validate → Document #methodology
• [tool] Slash commands provide uniform process automation #automation
• [agent-pattern] Three specialized agents handle different implementation domains #specialization
• [success-metric] Time from spec to working implementation measures process efficiency #measurement
• [learning] Process should evolve naturally based on what works in practice #adaptation
• [format] Living specifications use checklists for progress tracking instead of static status headers #documentation
• [evolution] Specs evolve throughout implementation maintaining value as working documents #continuous-improvement

Relations

• spec Spec-2: Slash Commands Reference
• spec Spec-3: Agent Definitions