agile-context-engineering 0.1.0 → 0.2.1

package/LICENSE

@@ -19,3 +19,33 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+---
+
+ACKNOWLEDGEMENTS
+
+Portions of this project were adapted from GSD (Get Shit Done)
+by Lex Christopherson, licensed under the MIT License.
+https://github.com/coleam00/get-shit-done
+
+MIT License
+
+Copyright (c) 2025 Lex Christopherson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,125 +1,319 @@
-# ACE - Agile Context Engineering
+# ACE — Agile Context Engineering
 
-A spec-driven development system for AI coding assistants with Agile workflows.
+[![npm version](https://img.shields.io/npm/v/agile-context-engineering)](https://www.npmjs.com/package/agile-context-engineering)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16.7.0-brightgreen)](https://nodejs.org)
 
-## Supported Runtimes
+**Spec-driven development for AI coding assistants.**
 
-- **Claude Code** - Anthropic's Claude Code CLI
-- **OpenCode** - OpenCode AI coding assistant
-- **Gemini CLI** - Google's Gemini CLI
-- **Codex CLI** - OpenAI's Codex CLI
+ACE turns your AI coding assistant into a full agile team — product owner, architect, code reviewer, and more — working from crystal-clear specs instead of vague prompts. Every story gets deep research, multi-agent execution, automated code review, and living documentation that grows with your project.
+
+---
+
+## Why ACE?
+
+If you've been part of software development in any capacity in the last 10-15 years, you've probably heard of Agile. If so — ACE is for you. It brings the full agile workflow to AI-assisted development: structured planning, incremental delivery, and living documentation, all managed by specialized AI agents.
+
+If not, here's the TLDR — Agile breaks work down into manageable pieces:
+
+```
+Product Vision        The north star — what you're building and why
+  └── Backlog         Epics and features organized by priority
+       └── Feature    A deliverable capability (1-2 sprints)
+            └── Story A user-facing work item with clear acceptance criteria (1-3 days)
+```
+
+You start with a vision, break it into a backlog of epics and features, decompose features into stories, then execute stories one by one. Each story is small enough to reason about clearly, but connected to the bigger picture through the hierarchy above it.
+
+**What makes ACE different:**
+- **Spec-driven** — Stories have crystal-clear acceptance criteria with zero assumptions. Every story goes through 5 research passes before a single line of code is written
+- **Multi-agent** — 8 specialized agents (Product Owner, Architect, Code Reviewer, Wiki Mapper, etc.) work in parallel. For larger stories, ACE leverages Claude Code's [Agent Teams](https://code.claude.com/docs/en/agent-teams) — unlike regular subagents that silently do work and report back, Agent Teams are fully independent Claude Code sessions that share a task list, message each other directly, coordinate on shared interfaces, and self-organize. ACE decomposes the technical solution into independent work streams, assigns each to a teammate with owned files, and adds a dedicated reviewer teammate that monitors code quality in real-time. The lead coordinates, approves each teammate's plan before they start implementing, and integrates the results
+- **GitHub Project management** — On top of generating local artifacts, ACE can optionally sync with GitHub — creating issues for epics, features, and stories, tracking status on project boards, and updating labels as work progresses through the pipeline
+- **Living wiki** — ACE maps all your code into a project wiki and updates it after every story, so the AI always has architectural overview context when planning new work
+- **Purpose-built CLI tooling** — A dedicated CLI (`ace-tools`) offloads infrastructure work outside the AI's context window — environment detection, markdown parsing, path computation, model resolution, state updates, and GitHub GraphQL operations all return structured JSON in a single call, saving tokens and avoiding shell escaping issues
+
+---
+
+## How It Works
+
+### Getting Started — `/ace:help`
+
+Run `/ace:help` at any point to see what's set up and what to do next. It checks for six foundation documents: **product vision**, **system architecture**, **system structure**, **coding standards**, **testing framework**, and **settings**. These documents are generated by the foundation commands (`plan-product-vision`, `map-system`, `init-coding-standards`) and are used by all subsequent planning and execution commands to stay aligned with your project's architecture, conventions, and goals.
+
+```mermaid
+flowchart LR
+    H["ace:help"] --> checks{{"checks for"}}
+    checks --> files["vision · architecture<br/>structure · standards<br/>testing · settings"]
+    files --> D["Dashboard +<br/>Next Command"]
+
+    style H fill:#4A90D9,color:#fff,font-size:12px
+    style checks fill:none,stroke:none,color:#888,font-size:11px
+    style files fill:#f5f5f5,stroke:#ccc,font-size:11px
+    style D fill:#2ECC71,color:#fff,font-size:12px
+```
+
+### Full Lifecycle
+
+```mermaid
+flowchart TD
+    V["Vision"] -->|"produces<br/>product-vision.md"| B["Backlog"]
+    B -->|"produces<br/>backlog + GitHub Issues"| F["Feature"]
+    F -->|"produces<br/>feature spec + stories"| S["Story"]
+    S -->|"dispatches 4 parallel agents"| R1
+
+    subgraph Research["Story Research — 5 passes"]
+        direction LR
+        R1["1. Deep<br/>Questioning"] --> R2["2. Wiki<br/>Research"]
+        R2 --> R3["3. External<br/>Analysis"]
+        R3 --> R4["4. Integration<br/>Analysis"]
+        R4 --> R5["5. Technical<br/>Solution"]
+    end
+
+    R5 -->|"produces<br/>AC + technical solution"| E["Execute"]
+    E -->|"produces<br/>source code + state"| RV["Review"]
+    RV -->|"produces<br/>review report"| W["Wiki"]
+
+    V -.- c1["plan-product-vision<br/>+ optional context docs"]
+    B -.- c2["plan-backlog<br/>+ reads product-vision.md"]
+    F -.- c3["plan-feature<br/>+ reads backlog"]
+    S -.- c4["plan-story<br/>+ reads feature + wiki"]
+    E -.- c5["execute-story<br/>+ reads AC + solution + standards"]
+    RV -.- c6["review-story<br/>+ reads standards"]
+    W -.- c7["map-story<br/>+ reads git diff"]
+
+    style V fill:#4A90D9,color:#fff
+    style B fill:#4A90D9,color:#fff
+    style F fill:#4A90D9,color:#fff
+    style S fill:#7B68EE,color:#fff
+    style R1 fill:#9B85FF,color:#fff
+    style R2 fill:#9B85FF,color:#fff
+    style R3 fill:#9B85FF,color:#fff
+    style R4 fill:#9B85FF,color:#fff
+    style R5 fill:#9B85FF,color:#fff
+    style Research fill:#f0ecff,stroke:#9B85FF
+    style E fill:#2ECC71,color:#fff
+    style RV fill:#E67E22,color:#fff
+    style W fill:#1ABC9C,color:#fff
+    style c1 fill:none,stroke:none,color:#666
+    style c2 fill:none,stroke:none,color:#666
+    style c3 fill:none,stroke:none,color:#666
+    style c4 fill:none,stroke:none,color:#666
+    style c5 fill:none,stroke:none,color:#666
+    style c6 fill:none,stroke:none,color:#666
+    style c7 fill:none,stroke:none,color:#666
+```
+
+---
 
 ## Installation
 
+ACE supports [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [Crush](https://github.com/crushai/crush) (formerly [OpenCode](https://github.com/opencode-ai/opencode)) as runtimes.
+
+> **Note:** ACE has been primarily developed and tested with Claude Code. Crush support is functional (the installer transforms all paths automatically), but has not been thoroughly tested end-to-end. If you encounter issues running ACE in Crush, please [open an issue](https://github.com/agile-context-engineering/ace/issues).
+
 ```bash
 npx agile-context-engineering
 ```
 
-### Options
+This launches an interactive installer. You can also use flags for non-interactive install:
 
 ```bash
-npx agile-context-engineering --claude --local   # Claude Code, local install
-npx agile-context-engineering --opencode --global # OpenCode, global install
-npx agile-context-engineering --gemini --local    # Gemini CLI, local install
-npx agile-context-engineering --codex             # Codex CLI (always global)
+npx agile-context-engineering --claude --global   # Claude Code, global install
+npx agile-context-engineering --claude --local    # Claude Code, local (project-only)
+npx agile-context-engineering --opencode --global # Crush (formerly OpenCode), global install
 npx agile-context-engineering --all --global      # All runtimes, global install
 ```
 
-## Commands
+### Prerequisites
 
-| Command | Description |
-|---------|-------------|
-| `/ace:init` | Initialize ACE in your project |
-| `/ace:plan-project` | Plan your project with epics and features |
-| `/ace:plan-epic` | Break an epic into features |
-| `/ace:plan-feature` | Break a feature into stories |
-| `/ace:plan-story` | Create a new user story |
-| `/ace:refine-story` | Prepare a story for execution |
-| `/ace:execute-story` | Execute a story with atomic commits |
-| `/ace:verify-story` | Verify a completed story |
-
-## Workflow
+| Requirement | Purpose |
+|---|---|
+| [Node.js](https://nodejs.org) >= 16.7.0 | Runs the installer and CLI tools |
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Crush](https://github.com/crushai/crush) / [OpenCode](https://github.com/opencode-ai/opencode) | AI coding assistant runtime |
+| [GitHub CLI (`gh`)](https://cli.github.com/) | Required for GitHub issue tracking and project board integration |
+
+---
+
+## Quick Start
+
+Run `/ace:help` first. It will show you which foundation documents are missing and suggest the exact command to generate each one. Follow its suggestions until the dashboard shows everything complete.
+
+Once the dashboard is fully green, you're ready to build:
 
 ```
-Epic → Feature → Story → Tasks
-  ↓       ↓        ↓       ↓
-Plan → Refine → Execute → Verify
+/ace:plan-backlog            # Create epics and features from your vision
+/ace:plan-feature            # Break a feature into stories
+/ace:plan-story              # Deep-plan a story (triggers 5 research passes)
+/ace:execute-story           # Execute with multi-agent teams
 ```
 
-### Agile Hierarchy
+---
 
-- **Epic**: Large body of work (1-3 months)
-- **Feature**: Deliverable functionality (1-2 sprints)
-- **Story**: User-facing work item (1-3 days)
-- **Task**: Atomic implementation step (30 min - 2 hours)
 
-## Getting Started
+## Key Features
 
-1. Install ACE in your project:
-   ```bash
-   npx agile-context-engineering --claude --local
-   ```
+### Agent Teams
 
-2. Initialize ACE:
-   ```
-   /ace:init
-   ```
+ACE can leverage Claude Code's [Agent Teams](https://code.claude.com/docs/en/agent-teams) for story execution. As opposed to regular subagents — which silently do work in isolation and report results back — Agent Teams are fully independent Claude Code sessions that:
 
-3. Plan your project:
-   ```
-   /ace:plan-project
-   ```
+- **Share a task list** — teammates claim tasks, mark them complete, and blocked tasks auto-unblock when dependencies resolve
+- **Message each other directly** — teammates coordinate on shared interfaces, ask questions, and challenge each other's approaches without going through the lead
+- **Each have their own context window** — no shared context limit; each teammate gets a fresh 200k window
+- **Require plan approval** — the lead reviews and approves each teammate's implementation plan before they start writing code
+- **Self-organize** — after finishing a task, teammates pick up the next available one on their own
 
-4. Continue planning down the hierarchy:
-   ```
-   /ace:plan-epic E1
-   /ace:plan-feature E1-F1
-   /ace:plan-story E1-F1 "User can sign up"
-   ```
+ACE orchestrates this by decomposing the technical solution into independent work streams (e.g., "state-layer", "ui-layer", "integration", "tests"), assigning each to a teammate with explicitly owned files (no overlap), and spawning a dedicated reviewer teammate that watches for anti-patterns, coding standards violations, and dead code as other teammates work.
 
-5. Execute and verify:
-   ```
-   /ace:refine-story E1-F1-S1
-   /ace:execute-story E1-F1-S1
-   /ace:verify-story E1-F1-S1
-   ```
+### 8 Specialized Agents
 
-## GitHub Integration
+| Agent | Role |
+|---|---|
+| **Product Owner** | Requirements gathering, decomposition, prioritization, estimation, backlog management |
+| **Technical Architect** | Solution design, architecture decisions, Clean Architecture and SOLID enforcement |
+| **Code Discovery Analyst** | Deep repository analysis — extracts patterns, algorithms, data models, architectural decisions |
+| **Code Integration Analyst** | Analyzes how new features integrate while maintaining architecture and extensibility |
+| **Code Reviewer** | Completeness, correctness, code quality, anti-pattern detection, tech debt discovery |
+| **Wiki Mapper** | Writes structured wiki documents for the engineering knowledge base |
+| **Project Researcher** | Researches domain ecosystem to inform planning phases |
+| **Research Synthesizer** | Synthesizes outputs from parallel research agents into coherent summaries |
 
-ACE can store epics, features, and stories as GitHub issues instead of local files.
+### ACE CLI Tooling (`ace-tools`)
 
-Initialize with GitHub:
-```
-/ace:init --github
-```
+The AI doesn't do everything itself. ACE offloads infrastructure-heavy operations to a purpose-built Node.js CLI, keeping workflows fast and token-efficient:
+
+- **Compound init commands** — Each workflow starts with a single `init` call that gathers 15-20 environment facts: brownfield detection, model resolution, story parsing, metadata extraction, path computation, and file existence checks — all returned as structured JSON
+- **Atomic state updates** — One command updates the story file, feature file, and product backlog together, with cascading logic that auto-promotes feature status when all stories complete
+- **GitHub operations** — Issue creation, type assignment, project board placement, field updates, and parent linking happen in one call. Markdown bodies use `--body-file` to avoid shell escaping issues with code blocks and backticks
+- **Bulk sync** — Pushes local story/feature content to GitHub issues and syncs project board status in a single command
+- **Markdown parsing** — Story headers, metadata fields, acceptance criteria, requirements sections, and wiki references are extracted and categorized outside the context window
+- **Environment detection** — Brownfield detection walks the directory tree checking 10+ code file extensions and package files, reused across every workflow
 
-This creates GitHub labels and uses `gh` CLI for issue management.
+### GitHub Integration
 
-## Runtime-Specific Notes
+ACE works fully offline with local artifacts. Optionally, you can enable GitHub integration to sync epics, features, and stories as GitHub issues — with automatic status tracking, labels, and project board updates as work progresses through the pipeline.
 
-### Claude Code, OpenCode, Gemini CLI
-These runtimes support both global (`~/.claude`, `~/.opencode`, `~/.gemini`) and local (`.claude`, `.opencode`, `.gemini`) installation.
+Requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated.
 
-### Codex CLI
-Codex CLI only supports global installation (`~/.codex/skills/`). ACE creates skill files following Codex's `SKILL.md` convention.
 
 ## Project Structure
 
+ACE creates two directories in your project:
+
+**`.ace/`** — Internal artifacts that ACE needs to operate: configuration, feature specs, story specs, research outputs, and supporting documents. This is ACE's working directory and can be safely `.gitignore`d if you prefer to keep your repo clean.
+
+**`.docs/`** — Project-facing documents: the living wiki, product vision, and coding standards. These are meant to be committed — they provide valuable context for your team and for the AI across sessions.
+
 ```
 .ace/
-├── config.json      # ACE configuration
-├── backlog/         # Epics and features
+├── config.json           # ACE configuration (GitHub org, project, settings)
+├── backlog/              # Epics and features
 │   ├── E1-epic-name.md
 │   └── E1/
 │       └── F1-feature-name.md
-├── sprints/         # Sprint planning
-└── research/        # Research findings
+└── stories/              # Story specs and research artifacts
 
-PROJECT.md           # Project vision
-BACKLOG.md          # Product backlog overview
-STATE.md            # Current state and decisions
+.docs/
+├── wiki/                 # Living engineering knowledge base
+│   ├── system-wide/      # System-level architecture docs
+│   └── subsystems/       # Per-subsystem documentation
+├── product-vision.md     # Product vision document
+└── coding-standards.md   # Project coding standards
 ```
 
+## Living Wiki
+
+Every completed story triggers a wiki update. The wiki is the AI's institutional memory of your codebase — it's what allows agents to make informed decisions about where to put code, which patterns to follow, and how to wire new components into existing infrastructure.
+
+**System-wide docs** (`.docs/wiki/system-wide/`) provide the 30,000-foot view:
+
+| Document | What it captures |
+|---|---|
+| **system-structure.md** | Physical directory layout, every subsystem and its purpose, where each code file lives and what it does |
+| **system-architecture.md** | C4 diagrams, subsystem responsibility matrix, core data flows, tech stack |
+| **testing-framework.md** | Test frameworks, patterns, mocking strategies, coverage approach |
+| **coding-standards.md** | Language and framework conventions |
+| **tech-debt-index.md** | All known tech debt across subsystems, tracked by severity |
+
+**Subsystem docs** (`.docs/wiki/subsystems/[name]/`) go deep into each subsystem:
+
+| Folder | What it documents | How the AI uses it |
+|---|---|---|
+| **structure.md** | File tree, directory purposes, key file locations, where to add new code | Knows exactly where every file is and what it does |
+| **architecture.md** | Architectural pattern (Clean/N-Tier/CQRS), C4 L3 components, internal flows, dependency inventory | Understands the subsystem's internal design before making changes |
+| **systems/** | Domain components — file trees, entry points, data flows, sequence diagrams, state management, error propagation | Understands what exists before adding new code |
+| **patterns/** | Reusable structural templates — structure diagrams, current implementations, how to apply | Follows existing patterns instead of inventing new ones |
+| **cross-cutting/** | Shared infrastructure — DI containers, event systems, factories, registrations | Knows exactly where to register new components |
+| **guides/** | Step-by-step recipes for common tasks (e.g., "add a new API endpoint") | Follows proven procedures instead of guessing |
+| **decisions/** | Architecture Decision Records — why choices were made, alternatives rejected | Respects past decisions, doesn't re-litigate them |
+
+When planning a new story, the wiki research pass scans all relevant docs and attaches them to the story. When executing, the agent loads those references as context. After implementation, `map-story` updates the wiki with what changed — so the next story benefits from everything learned.
+
+## Commands
+
+### Getting Started
+
+| Command | Description |
+|---|---|
+| `/ace:help` | Check project initialization status and suggest next steps |
+
+### Foundation (one-time setup)
+
+| Command | Description |
+|---|---|
+| `/ace:plan-product-vision` | Create or update the product vision through architecture-aware questioning |
+| `/ace:init-coding-standards` | Generate a tailored `coding-standards.md` through codebase detection and user interview |
+| `/ace:map-system` | Map system-wide structure, architecture, and testing framework into `.docs/wiki/system-wide/` |
+| `/ace:map-subsystem` | Map a subsystem's structure, architecture, and knowledge docs into `.docs/wiki/subsystems/[name]/` |
+
+### Planning
+
+| Command | Description |
+|---|---|
+| `/ace:plan-backlog` | Create or refine the product backlog through vision-aware questioning and guided epic/feature planning |
+| `/ace:plan-feature` | Plan a feature through backlog-aware questioning, story decomposition, and guided specification |
+
+### Story Refinement
+
+| Command | Description |
+|---|---|
+| `/ace:plan-story` | Plan a story with crystal-clear acceptance criteria, then auto-dispatch 5 research passes |
+
+`/ace:plan-story` is where ACE really shines. After establishing acceptance criteria through deep questioning, it automatically dispatches up to 4 parallel research agents:
+
+1. **Deep questioning** — Collaborative refinement to eliminate all assumptions from acceptance criteria
+2. **Wiki research** — Searches the living wiki for relevant architectural context *(auto-dispatched)*
+3. **External analysis** — Studies similar implementations in reference repositories *(optional, auto-dispatched)*
+4. **Integration analysis** — Analyzes how the story integrates into the existing codebase *(auto-dispatched)*
+5. **Technical solution** — Designs the architecture, patterns, algorithms, and implementation plan *(auto-dispatched)*
+
+Each research pass can also be run standalone:
+
+| Command | Description |
+|---|---|
+| `/ace:research-story-wiki` | Research and curate wiki references relevant to a story |
+| `/ace:research-external-solution` | Code-level analysis of similar implementations in external repositories |
+| `/ace:research-integration-solution` | System integration analysis for fitting a story into the existing codebase |
+| `/ace:research-technical-solution` | Technical solution design — architecture, patterns, sequence diagrams, implementation plan |
+
+### Execution & Review
+
+| Command | Description |
+|---|---|
+| `/ace:execute-story` | Execute a fully-planned story — implements via solo or agent teams, runs code review, updates state, triggers wiki mapping |
+| `/ace:review-story` | Standalone code review — artifact verification, anti-pattern detection, coding standards enforcement, tech debt discovery |
+
+### Documentation
+
+| Command | Description |
+|---|---|
+| `/ace:map-story` | Update living knowledge docs after story implementation or for existing undocumented code |
+
+---
+
+## Acknowledgements
+
+Portions of this project were adapted from [GSD (Get Shit Done)](https://github.com/coleam00/get-shit-done) by Lex Christopherson, licensed under the MIT License.
+
 ## License
 
-MIT
+[MIT](LICENSE)