specsmd 0.0.1

package/README.md

@@ -0,0 +1,300 @@
+# specsmd
+
+**AI-native software development with multi-agent orchestration.**
+
+specsmd implements the [AI-Driven Development Lifecycle (AI-DLC)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/) methodology as a set of markdown-based agents that work with your favorite AI coding tools.
+
+[![npm version](https://img.shields.io/npm/v/specsmd)](https://www.npmjs.com/package/specsmd)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## What is AI-DLC?
+
+AI-DLC is a reimagined software development methodology where **AI drives the conversation** and humans validate. Unlike traditional Agile where iterations span weeks, AI-DLC operates in **Bolts** - rapid iterations measured in hours or days.
+
+> "Traditional development methods were built for human-driven, long-running processes. AI-DLC reimagines the development lifecycle with AI as a central collaborator, enabling rapid cycles measured in hours or days rather than weeks."
+
+### AI-DLC vs Traditional Methods
+
+| Aspect | Agile/Scrum | AI-DLC |
+|--------|-------------|--------|
+| Iteration duration | Weeks (Sprints) | Hours/days (Bolts) |
+| Who drives | Human-driven, AI assists | AI-driven, human-validated |
+| Design techniques | Out of scope | Integrated (DDD, TDD, BDD) |
+| Task decomposition | Manual | AI-powered |
+| Phases | Repeating sprints | Rapid three-phase cycles (Inception → Construction → Operations) |
+| Rituals | Daily standups, retrospectives | Mob Elaboration, Mob Construction |
+
+---
+
+## How It Works
+
+specsmd provides four specialized agents that guide you through the entire development lifecycle:
+
+```
+                    ┌─────────────────┐
+                    │  Master Agent   │  Orchestrates & navigates
+                    └────────┬────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        ▼                    ▼                    ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│   Inception   │ → │ Construction  │ → │  Operations   │
+│     Agent     │   │     Agent     │   │     Agent     │
+└───────────────┘   └───────────────┘   └───────────────┘
+  Capture intent      Execute bolts      Deploy & monitor
+  Define units        Build & test       Verify & scale
+  Plan stories        Validate stages
+```
+
+### The Three Phases
+
+| Phase | Agent | Purpose | Key Outputs |
+|-------|-------|---------|-------------|
+| **Inception** | Inception Agent | Capture intents, elaborate requirements, decompose into units | User stories, NFRs, Unit definitions, Bolt plans |
+| **Construction** | Construction Agent | Execute bolts through domain design → logical design → code → test | Domain models, Technical designs, Code, Tests |
+| **Operations** | Operations Agent | Deploy, verify, and monitor | Deployment units, Monitoring, Runbooks |
+
+---
+
+## Quick Start
+
+### Installation
+
+```bash
+npx specsmd install
+```
+
+The installer detects your AI coding tools (Claude Code, Cursor, GitHub Copilot) and sets up:
+- Agent definitions and skills
+- Memory bank structure for context persistence
+- Slash commands for easy agent invocation
+
+### Initialize Your Project
+
+```bash
+# Start the Master Agent
+/specsmd-master-agent
+
+# Then type:
+project-init
+```
+
+This guides you through establishing:
+- **Tech Stack** - Languages, frameworks, databases, infrastructure
+- **Coding Standards** - Formatting, linting, naming, testing strategy
+- **System Architecture** - Architecture style, API design, state management
+- **UX Guide** - Design system, styling, accessibility (optional)
+- **API Conventions** - API style, versioning, response formats (optional)
+
+### Create Your First Intent
+
+```bash
+/specsmd-inception-agent intent-create
+```
+
+An **Intent** is your high-level goal:
+- "User authentication system"
+- "Product catalog with search"
+- "Payment processing integration"
+
+The agent will:
+1. Ask clarifying questions to minimize ambiguity
+2. Elaborate into user stories and NFRs
+3. Define system context
+4. Decompose into loosely-coupled units
+
+### Plan and Execute Bolts
+
+```bash
+# Plan bolts for your stories
+/specsmd-inception-agent bolt-plan
+
+# Execute a bolt
+/specsmd-construction-agent bolt-start
+```
+
+Each bolt goes through validated stages:
+1. **Domain Model** - Model business logic using DDD principles
+2. **Technical Design** - Apply patterns and make architecture decisions
+3. **ADR Analysis** - Document significant decisions (optional)
+4. **Implement** - Generate production code
+5. **Test** - Verify correctness with automated tests
+
+**Human validation happens at each stage gate.**
+
+---
+
+## Key Concepts
+
+### Intent
+A high-level statement of purpose that encapsulates what needs to be achieved - whether a business goal, feature, or technical outcome. It serves as the starting point for AI-driven decomposition.
+
+### Unit
+A cohesive, self-contained work element derived from an Intent. Units are loosely coupled and can be developed independently. Analogous to a Subdomain (DDD) or Epic (Scrum).
+
+### Bolt
+The smallest iteration in AI-DLC, designed for rapid implementation. Unlike Sprints (weeks), Bolts are **hours to days**. Each bolt encapsulates a well-defined scope of work.
+
+| Type | Best For | Stages |
+|------|----------|--------|
+| **DDD Construction** | Complex business logic, domain modeling | Model → Design → ADR → Implement → Test |
+| **TDD Construction** | Well-defined interfaces, test-first | Test → Implement → Refactor |
+| **BDD Construction** | User-facing features, acceptance criteria | Scenario → Implement → Verify |
+| **Spike** | Research, exploration, unknowns | Explore → Document |
+
+### Memory Bank
+File-based storage for all project artifacts. Maintains context across agent sessions and provides traceability between artifacts.
+
+### Standards
+Project decisions that inform AI code generation. Standards ensure consistency across all generated code and documentation.
+
+---
+
+## Project Structure
+
+After installation:
+
+```
+.specsmd/
+├── manifest.yaml              # Installation manifest
+└── aidlc/                     # AI-DLC flow
+    ├── agents/                # Agent definitions
+    ├── skills/                # Agent capabilities
+    ├── templates/             # Artifact templates
+    │   └── standards/         # Standards facilitation guides
+    └── memory-bank.yaml       # Memory bank schema
+
+memory-bank/                   # Created after project-init
+├── intents/                   # Your captured intents
+│   └── {intent-name}/
+│       ├── requirements.md
+│       ├── system-context.md
+│       └── units/
+├── bolts/                     # Bolt execution records
+├── standards/                 # Project standards
+│   ├── tech-stack.md
+│   ├── coding-standards.md
+│   └── ...
+└── operations/                # Deployment context
+```
+
+---
+
+## Agent Commands
+
+### Master Agent
+```bash
+/specsmd-master-agent
+```
+| Command | Purpose |
+|---------|---------|
+| `project-init` | Initialize project with standards |
+| `analyze-context` | View current project state |
+| `route-request` | Get directed to the right agent |
+| `explain-flow` | Learn about AI-DLC methodology |
+| `answer-question` | Get help with any specsmd question |
+
+### Inception Agent
+```bash
+/specsmd-inception-agent
+```
+| Command | Purpose |
+|---------|---------|
+| `intent-create` | Create a new intent |
+| `intent-list` | List all intents |
+| `requirements` | Elaborate intent requirements |
+| `context` | Define system context |
+| `units` | Decompose into units |
+| `story-create` | Create stories for a unit |
+| `bolt-plan` | Plan bolts for stories |
+| `review` | Review inception artifacts |
+
+### Construction Agent
+```bash
+/specsmd-construction-agent
+```
+| Command | Purpose |
+|---------|---------|
+| `bolt-start` | Start/continue executing a bolt |
+| `bolt-status` | Check bolt progress |
+| `bolt-list` | List all bolts |
+| `bolt-replan` | Replan bolts if needed |
+
+### Operations Agent
+```bash
+/specsmd-operations-agent
+```
+| Command | Purpose |
+|---------|---------|
+| `build` | Build the project |
+| `deploy` | Deploy to environment |
+| `verify` | Verify deployment |
+| `monitor` | Set up monitoring |
+
+---
+
+## Why specsmd?
+
+### AI-Native, Not AI-Retrofitted
+Built from the ground up for AI-driven development. AI-DLC is a reimagination based on first principles, not a retrofit of existing methods.
+
+### Human Oversight as Loss Function
+Validation at each stage catches errors early before they cascade downstream. Each validation transforms artifacts into rich context for subsequent stages.
+
+### Design Techniques Built-In
+DDD, TDD, and BDD are integral to the methodology - not optional add-ons. This addresses the "whitespace" in Agile that has led to quality issues.
+
+### Tool Agnostic
+Works with Claude Code, Cursor, GitHub Copilot, and other AI coding assistants. Markdown-based agents work anywhere.
+
+### Context Persistence
+Memory bank ensures AI agents have full project context across sessions. All artifacts are linked for backward and forward traceability.
+
+---
+
+## Supported Tools
+
+| Tool | Status | Installation |
+|------|--------|--------------|
+| **Claude Code** | Full support | Slash commands in `.claude/commands/` |
+| **Cursor** | Full support | Rules in `.cursor/rules/` (`.mdc` format) |
+| **GitHub Copilot** | Full support | Agents in `.github/agents/` (`.agent.md` format) |
+| **Google Antigravity** | Full support | Agents in `.agent/agents/` |
+
+---
+
+## FAQ
+
+**Q: Agents don't seem to remember previous context?**
+Each agent invocation starts fresh. Agents read context from the Memory Bank at startup. Ensure artifacts are saved after each step.
+
+**Q: How do I reset project state?**
+Clear the `memory-bank/` directory to reset all artifacts. To remove specsmd entirely, delete the `.specsmd/` directory and tool-specific command files.
+
+**Q: Can I use specsmd with existing Agile workflows?**
+AI-DLC is designed as a reimagination, not a retrofit. However, familiar concepts (user stories, acceptance criteria) are retained to ease transition.
+
+**Q: What project types is this suited for?**
+specsmd is designed for building complex systems that demand architectural complexity, trade-off management, and scalability. Simpler systems may be better suited for low-code/no-code approaches.
+
+---
+
+## Resources
+
+- [AI-DLC Specification (AWS)](https://aws.amazon.com/blogs/devops/ai-driven-development-life-cycle/)
+- [specs.md](https://specs.md)
+
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  Built with AWS' AI-DLC methodology by the <a href="https://specs.md">specs.md</a> team.
+</p>

package/bin/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const installer = require('../lib/installer');
+const packageJson = require('../package.json');
+
+program
+    .version(packageJson.version)
+    .description(packageJson.description);
+
+program
+    .command('install')
+    .description('Interactively install a specsmd flow')
+    .action(installer.install);
+
+program
+    .command('uninstall')
+    .description('Uninstall specsmd from the current project')
+    .action(installer.uninstall);
+
+program.parse(process.argv);

package/flows/aidlc/README.md

@@ -0,0 +1,372 @@
+# AI-DLC Flow - specsmd
+
+Welcome to the **AI-DLC (AI-Driven Development Life Cycle)** flow for specsmd!
+
+## What is AI-DLC?
+
+AI-DLC is an **AWS methodology** for AI-native software development that optimizes for how AI agents work best. Unlike traditional methodologies, AI-DLC:
+
+- Uses **concentrated rapid planning** (Mob Elaboration) that "condenses weeks into hours"
+- Works in **focused bolt sessions** (hours or days, not fixed sprints)
+- Follows **DDD (Domain-Driven Design)** principles
+- Maintains **persistent context** across sessions through memory bank
+- Operates in **three sequential phases**: Inception → Construction → Operations
+
+## Three Phases
+
+### 1. Inception Phase
+
+**Goal**: Complete planning and design before construction begins
+
+**Activities**:
+
+- Gather requirements
+- Create user stories
+- Design architecture
+- Decompose into Units of Work
+- Plan Bolt instances
+
+**Command**: `/specsmd-inception-agent --intent="intent-name"`
+
+**Output**:
+
+- Requirements documented
+- Stories created
+- Architecture designed
+- Units decomposed
+- Bolts planned
+
+### 2. Construction Phase
+
+**Goal**: Build working software through iterative bolt execution
+
+**Activities**:
+
+- Execute bolts through DDD stages:
+  1. **domain-design** - Model business logic
+  2. **logical-design** - Apply NFRs and patterns
+  3. **code-generation** - Implement code
+  4. **testing** - Automated testing
+
+**Command**: `/specsmd-construction-agent --unit="unit-name"`
+
+**Output**:
+
+- Domain models
+- Logical designs
+- Implementation code
+- Comprehensive tests
+
+### 3. Operations Phase
+
+**Goal**: Deploy and operate the system
+
+**Activities**:
+
+- Build deployment artifacts
+- Deploy to environments
+- Verify deployments
+- Setup monitoring
+
+**Command**: `/specsmd-operations-agent --unit="unit-name"`
+
+**Output**:
+
+- Deployed services
+- Monitoring dashboards
+- Deployment documentation
+
+## Artifact Ownership Matrix
+
+| Phase / Agent | Primary Output Artifacts | Description |
+|--------------|-------------------------|-------------|
+| **Inception** | **Requirements** | Functional & Non-functional requirements |
+| | **Stories** | User stories scoped to a Unit |
+| | **System Context** | High-level boundaries & actors |
+| | **Unit Decomposition** | Identification of independent units |
+| | **Bolt Plans** | Planned work sessions |
+| **Construction** | **Domain Design** | Entities, Aggregates, Value Objects |
+| | **Logical Design** | APIs, Schemas, Cloud Resources |
+| | **Code** | Source code implementation |
+| | **Tests** | Unit, Integration, & E2E tests |
+| **Operations** | **Build Artifacts** | Docker images, binaries, bundles |
+| | **Infrastructure** | Terraform/CloudFormation/CDK |
+| | **Documentation** | Runbooks, API docs |
+
+## Decomposition Hierarchy
+
+AI-DLC distinguishes between the **Data Hierarchy** (what we build) and **Execution** (how we build it).
+
+### Data Hierarchy (Structural)
+
+```text
+Intent (feature/capability)
+  └── Unit (independently deployable component)
+      └── Story (individual user story or task)
+```
+
+### Execution (Process)
+
+**Bolts** are time-boxed execution sessions scoped to a **Unit**. A Unit may require multiple Bolts to complete all its Stories.
+
+**Example**:
+
+- **Intent**: User Authentication
+  - **Unit**: Auth Service
+    - **Story 1**: User Registration
+    - **Story 2**: Login
+    - **Bolt 1**: Implement Registration (executes Story 1)
+    - **Bolt 2**: Implement Login (executes Story 2)
+
+## Agent Capabilities & Slash Commands
+
+### Core Agent Commands (Slash Commands)
+
+These are the primary entry points defined in `.cursor/commands` (or your agentic coding tool's equivalent), mapping to `src/flows/aidlc/commands/`:
+
+- `/specsmd-master-agent` - **Start Here**. The Master Orchestrator that routes you to the right place.
+- `/specsmd-inception-agent` - Start Inception phase
+- `/specsmd-construction-agent` - Start Construction phase
+- `/specsmd-operations-agent` - Start Operations phase
+
+### Agent Skills (Internal)
+
+Agents execute these skills internally. You generally don't run these directly as slash commands, but the agents use them to perform work.
+
+- **Inception**: Gather Requirements, Create Stories, Define Context, Decompose Units
+- **Construction**: Plan Bolts, Start Bolts, Manage Bolt Status
+- **Operations**: Build, Deploy, Verify
+
+## Memory Bank Structure
+
+> **Note**: The structure below is an **example**. The authoritative source of truth for the memory bank schema is `.specsmd/aidlc/memory-bank.yaml`. Agents read that file to determine where to place artifacts.
+
+All artifacts are stored in the `memory-bank/` directory:
+
+```text
+memory-bank/
+├── intents/                          # Feature intents
+│   └── {intent-name}/
+│       ├── requirements.md           # Functional & non-functional requirements
+│       ├── system-context.md         # High-level boundaries & actors
+│       ├── units.md                  # Unit decomposition overview
+│       └── units/
+│           └── {unit-name}/
+│               ├── unit-brief.md     # Unit scope and details
+│               └── stories/
+│                   ├── 001-{title}.md
+│                   └── 002-{title}.md
+├── bolts/                            # Bolt execution records
+│   └── {bolt-id}/
+│       ├── bolt.md                   # Bolt instance metadata
+│       ├── ddd-01-domain-model.md    # Stage 1: Domain modeling
+│       ├── ddd-02-technical-design.md # Stage 2: Technical design
+│       └── ddd-03-test-report.md     # Stage 5: Test report
+├── standards/                        # Project standards
+│   ├── tech-stack.md
+│   ├── coding-standards.md
+│   └── system-architecture.md
+└── operations/                       # Deployment context
+```
+
+## Quick Start Guide
+
+### 1. Create Your First Intent
+
+Open your AI coding tool (Claude Code, Cursor, etc.) and type:
+
+```text
+/specsmd-master-agent
+```
+
+Then type `intent-create` to create your intent (e.g., "user-authentication").
+
+### 2. Run Inception Phase
+
+```text
+/specsmd-inception-agent --intent="user-authentication"
+```
+
+Work through the Inception menu:
+
+1. Gather Requirements
+2. Create Stories
+3. Design Architecture
+4. Decompose into Units
+5. Plan Bolts
+6. Review & Complete
+
+### 3. Execute Construction
+
+```text
+/specsmd-construction-agent --unit="auth-service"
+```
+
+Start your first bolt and work through the DDD stages:
+
+1. Domain Design
+2. Logical Design
+3. Code Generation
+4. Testing
+
+### 4. Deploy with Operations
+
+```text
+/specsmd-operations-agent --unit="auth-service"
+```
+
+Deploy your unit:
+
+1. Build Deployment Artifacts
+2. Deploy to Environment
+3. Verify Deployment
+4. Setup Monitoring
+
+## Key Principles
+
+### 1. Mob Elaboration (Rapid Planning)
+
+AI-DLC uses **concentrated rapid planning** during Inception. Instead of distributing planning across multiple sprints, you complete all planning in hours (not weeks) to give AI complete cross-unit context.
+
+### 2. AI Plans, Human Validates
+
+The AI suggests decompositions and designs, but humans review and approve all decisions.
+
+### 3. Bolts are Flexible
+
+Bolts take "hours or days" depending on complexity - they're not fixed-duration like sprints.
+
+### 4. DDD Focus
+
+Domain-Driven Design principles guide the entire Construction phase.
+
+### 5. Persistent Context
+
+Everything is stored in the memory bank so context is never lost between sessions.
+
+## Workflow Example
+
+Here's a complete workflow for building a feature:
+
+1. **Create Intent**
+
+   ```text
+   /specsmd-master-agent
+   # Then type: intent-create
+   # Create "user-authentication" intent
+   ```
+
+2. **Inception Phase**
+
+   ```text
+   /specsmd-inception-agent --intent="user-authentication"
+   # Complete all inception activities
+   # Result: 2 units planned with 3 bolts total
+   ```
+
+3. **Construction - Unit 1**
+
+   ```text
+   /specsmd-construction-agent --unit="auth-service"
+   # Execute auth-service-bolt-1 through all stages
+   # Execute auth-service-bolt-2 through all stages
+   # Result: Auth service fully implemented and tested
+   ```
+
+4. **Construction - Unit 2**
+
+   ```text
+   /specsmd-construction-agent --unit="email-service"
+   # Execute email-service-bolt-1
+   # Result: Email service implemented
+   ```
+
+5. **Operations**
+
+   ```text
+   /specsmd-operations-agent --unit="auth-service"
+   # Build, deploy, verify
+   # Result: Auth service running in production
+
+   /specsmd-operations-agent --unit="email-service"
+   # Build, deploy, verify
+   # Result: Email service running in production
+   ```
+
+## Tips for Success
+
+### Planning
+
+- Be thorough in Inception - it pays off during Construction
+- Document NFRs clearly - they affect logical design
+- Group related stories into the same bolt
+
+### Construction
+
+- Follow the DDD stages in order
+- Don't skip testing
+- Keep bolts focused (5-8 stories max)
+- Update memory bank artifacts as you progress
+
+### Operations
+
+- Always deploy to staging first
+- Run smoke tests after every deployment
+- Setup monitoring from the start
+- Document runbooks for on-call engineers
+
+## Agents
+
+Three specialized agents guide you through AI-DLC:
+
+1. **Master Orchestrator** (`agents/master-agent.md`)
+   - Central entry point
+   - Workflow routing
+   - State analysis
+
+2. **Inception Agent** (`agents/inception-agent.md`)
+   - Requirements gathering
+   - Story creation
+   - Architecture design
+   - System Context definition
+   - Unit decomposition
+   - Bolt planning
+
+3. **Construction Agent** (`agents/construction-agent.md`)
+   - Bolt execution
+   - DDD stage guidance
+   - Code generation
+   - Testing
+
+4. **Operations Agent** (`agents/operations-agent.md`)
+   - Build artifacts
+   - Deployment
+   - Verification
+   - Monitoring
+
+## Learn More
+
+- **Official AI-DLC Documentation**: See `/resource/aidlc-pdf-dump.txt` in the specsmd repository
+- **Methodology Notes**: See `specs/flows/aidlc/methodology-notes.md`
+- **Agent Details**: Read the agent files in `.specsmd/aidlc/agents/`
+
+## Getting Help
+
+If you get stuck:
+
+1. **Ask the Agent**: Just ask the Master or any agent your question. They can read the memory bank directly.
+
+## Customization
+
+You can customize this flow by editing:
+
+- `.specsmd/aidlc/memory-bank.yaml` - Memory bank structure
+- `agents/*-agent.md` - Agent directives and behaviors
+- `commands/*.md` - Slash command definitions
+- `.specsmd/aidlc/templates/` - Templates used by agents
+
+---
+
+**Happy building with AI-DLC!** 🚀
+
+*This is the official AI-DLC implementation by specsmd, following the AWS AI-DLC methodology.*