agile-context-engineering 0.1.0

package/commands/ace-init.md

@@ -0,0 +1,254 @@
+# /ace:init - Initialize ACE in Your Project
+
+Initialize Agile Context Engineering (ACE) for spec-driven development with Claude Code or OpenCode.
+
+## Usage
+
+```
+/ace:init [--github]
+```
+
+### Options
+
+- `--github` - Create items as GitHub issues instead of local files (requires `gh` CLI)
+
+## Behavior
+
+When invoked, this command will:
+
+1. **Check prerequisites**
+   - Verify you're in a git repository
+   - Check if ACE is already initialized
+   - If `--github` flag is used, verify `gh` CLI is authenticated
+
+2. **Create ACE directory structure**
+   ```
+   .ace/
+   ├── config.json          # ACE configuration
+   ├── backlog/             # Epic and feature definitions
+   ├── sprints/             # Sprint planning and tracking
+   └── research/            # Domain research and findings
+   ```
+
+3. **Create initial project files**
+   - `PROJECT.md` - Project vision and goals
+   - `BACKLOG.md` - Product backlog overview
+   - `STATE.md` - Current project state and decisions
+
+4. **Configure GitHub integration** (if `--github` flag used)
+   - Create GitHub labels for epics, features, stories
+   - Set up issue templates
+
+## Instructions for Claude
+
+<ace-init>
+
+### Step 1: Verify Prerequisites
+
+Check if we're in a git repository:
+```bash
+git rev-parse --is-inside-work-tree
+```
+
+Check if ACE is already initialized:
+- Look for `.ace/config.json` file
+- If exists, ask user if they want to reinitialize
+
+### Step 2: Gather Project Information
+
+Ask the user for:
+1. **Project name** - What is this project called?
+2. **Project description** - One-line description of what this project does
+3. **Storage preference** - Local files or GitHub issues?
+4. **GitHub integration** - If GitHub, which repo? (auto-detect from git remote if possible)
+
+### Step 3: Create Directory Structure
+
+Create the following structure:
+
+```
+.ace/
+├── config.json
+├── backlog/
+├── sprints/
+└── research/
+```
+
+### Step 4: Create Configuration File
+
+Create `.ace/config.json`:
+
+```json
+{
+  "version": "0.1.0",
+  "projectName": "<project-name>",
+  "description": "<project-description>",
+  "storage": "local|github",
+  "github": {
+    "enabled": false,
+    "repo": null,
+    "labels": {
+      "epic": "ace:epic",
+      "feature": "ace:feature",
+      "story": "ace:story",
+      "task": "ace:task"
+    }
+  },
+  "createdAt": "<timestamp>",
+  "hierarchy": {
+    "levels": ["epic", "feature", "story", "task"],
+    "current": {
+      "epic": null,
+      "feature": null,
+      "story": null,
+      "sprint": null
+    }
+  }
+}
+```
+
+### Step 5: Create PROJECT.md
+
+Create `PROJECT.md` in the repository root:
+
+```markdown
+# <Project Name>
+
+> <One-line description>
+
+## Vision
+
+<!-- Describe the long-term vision for this project -->
+
+## Goals
+
+<!-- List 3-5 key goals this project aims to achieve -->
+
+## Non-Goals
+
+<!-- What is explicitly out of scope -->
+
+## Success Criteria
+
+<!-- How will you measure success? -->
+
+---
+
+*Managed with [ACE](https://github.com/agile-context-engineering/ace) - Agile Context Engineering*
+```
+
+### Step 6: Create BACKLOG.md
+
+Create `BACKLOG.md` in the repository root:
+
+```markdown
+# Product Backlog
+
+## Epics
+
+<!-- Epics are large bodies of work that can be broken down into features -->
+
+| ID | Epic | Status | Features |
+|----|------|--------|----------|
+| - | - | - | - |
+
+## Prioritized Features
+
+<!-- Features ready for sprint planning -->
+
+| Priority | Feature | Epic | Stories | Status |
+|----------|---------|------|---------|--------|
+| - | - | - | - | - |
+
+---
+
+*Use `/ace:plan-epic` to add epics, `/ace:plan-feature` to break them into features*
+```
+
+### Step 7: Create STATE.md
+
+Create `STATE.md` in the repository root:
+
+```markdown
+# Project State
+
+> Last updated: <timestamp>
+
+## Current Sprint
+
+**Sprint:** None
+**Goal:** N/A
+**Status:** Not started
+
+## Active Work
+
+<!-- Currently in-progress items -->
+
+| Item | Type | Assignee | Status |
+|------|------|----------|--------|
+| - | - | - | - |
+
+## Decisions Log
+
+<!-- Important decisions made during development -->
+
+| Date | Decision | Context | Alternatives Considered |
+|------|----------|---------|------------------------|
+| - | - | - | - |
+
+## Blockers
+
+<!-- Current blockers and their status -->
+
+| Blocker | Impact | Owner | Status |
+|---------|--------|-------|--------|
+| - | - | - | - |
+
+## Context Notes
+
+<!-- Important context for future sessions -->
+
+---
+
+*Updated automatically by ACE commands*
+```
+
+### Step 8: GitHub Setup (if enabled)
+
+If GitHub integration is enabled:
+
+1. Create labels:
+```bash
+gh label create "ace:epic" --color "7057ff" --description "ACE Epic - large body of work"
+gh label create "ace:feature" --color "0075ca" --description "ACE Feature - deliverable functionality"
+gh label create "ace:story" --color "008672" --description "ACE Story - user-facing work item"
+gh label create "ace:task" --color "d73a4a" --description "ACE Task - technical work item"
+gh label create "ace:blocked" --color "b60205" --description "ACE Blocked - waiting on dependency"
+gh label create "ace:sprint" --color "fbca04" --description "ACE Sprint - current sprint item"
+```
+
+2. Update config.json with GitHub settings
+
+### Step 9: Confirm Success
+
+Output a summary:
+
+```
+✓ ACE initialized successfully!
+
+Created:
+  - .ace/config.json
+  - .ace/backlog/
+  - .ace/sprints/
+  - .ace/research/
+  - PROJECT.md
+  - BACKLOG.md
+  - STATE.md
+
+Next steps:
+  1. Edit PROJECT.md to define your vision and goals
+  2. Run /ace:plan-project to create your initial epics
+  3. Run /ace:plan-epic to break epics into features
+```
+
+</ace-init>

package/commands/ace-plan-epic.md

@@ -0,0 +1,79 @@
+# /ace:plan-epic - Plan an Epic
+
+Break down an epic into features and define acceptance criteria.
+
+## Usage
+
+```
+/ace:plan-epic <epic-id>
+/ace:plan-epic E1
+```
+
+### Arguments
+
+- `epic-id` - The epic identifier (e.g., E1, E2)
+
+## Behavior
+
+This command helps you detail an epic by:
+- Defining all features within the epic
+- Setting acceptance criteria
+- Identifying dependencies between features
+- Estimating relative complexity
+
+## Instructions for Claude
+
+<ace-plan-epic>
+
+### Prerequisites
+
+1. Verify ACE is initialized
+2. Verify the epic exists in `.ace/backlog/`
+3. Read the epic file and understand context
+
+### Planning Flow
+
+1. **Review Epic Context**
+   - Read the epic definition
+   - Understand the user value
+   - Review any existing features
+
+2. **Feature Breakdown**
+   - Identify 3-8 features for this epic
+   - Each feature should be completable in 1-2 sprints
+   - Features should deliver demonstrable value
+
+3. **For Each Feature, Capture:**
+   - ID: E1-F1, E1-F2, etc.
+   - Name: Clear, action-oriented name
+   - Description: What this feature delivers
+   - User stories preview: High-level story count estimate
+   - Dependencies: Other features this depends on
+   - Acceptance criteria: How we know it's done
+
+4. **Create Feature Files**
+   - Save to `.ace/backlog/<epic-id>/F1-feature-name.md`
+
+5. **Update Epic File**
+   - Add features table
+   - Update status
+
+6. **GitHub Integration** (if enabled)
+   - Create feature issues linked to epic
+   - Add `ace:feature` label
+
+### Output
+
+```
+✓ Epic E1 planned!
+
+Features:
+  E1-F1: <Feature Name>
+  E1-F2: <Feature Name>
+  ...
+
+Next steps:
+  - Run /ace:plan-feature E1-F1 to break into stories
+```
+
+</ace-plan-epic>

package/commands/ace-plan-feature.md

@@ -0,0 +1,78 @@
+# /ace:plan-feature - Plan a Feature
+
+Break down a feature into user stories ready for sprint planning.
+
+## Usage
+
+```
+/ace:plan-feature <feature-id>
+/ace:plan-feature E1-F1
+```
+
+### Arguments
+
+- `feature-id` - The feature identifier (e.g., E1-F1)
+
+## Behavior
+
+This command helps you detail a feature by:
+- Defining user stories using the "As a... I want... So that..." format
+- Setting story acceptance criteria
+- Identifying technical considerations
+- Preparing stories for sprint planning
+
+## Instructions for Claude
+
+<ace-plan-feature>
+
+### Prerequisites
+
+1. Verify ACE is initialized
+2. Verify the feature exists
+3. Read feature and parent epic context
+
+### Planning Flow
+
+1. **Review Feature Context**
+   - Understand what this feature delivers
+   - Review acceptance criteria
+   - Understand dependencies
+
+2. **Story Breakdown**
+   - Create 2-5 user stories per feature
+   - Each story should be completable in 1-3 days
+   - Stories should be independently valuable
+
+3. **For Each Story, Capture:**
+   - ID: E1-F1-S1, etc.
+   - Title: Action-oriented title
+   - User Story: "As a [user], I want [goal], so that [benefit]"
+   - Acceptance Criteria: Testable conditions
+   - Technical Notes: Implementation considerations
+   - Estimate: Story points (1, 2, 3, 5, 8)
+
+4. **Create Story Files**
+   - Save to `.ace/backlog/<epic>/<feature>/S1-story-name.md`
+
+5. **GitHub Integration** (if enabled)
+   - Create story issues linked to feature
+   - Add `ace:story` label
+
+### Output
+
+```
+✓ Feature E1-F1 planned!
+
+Stories:
+  E1-F1-S1: <Story Title> (3 pts)
+  E1-F1-S2: <Story Title> (2 pts)
+  ...
+
+Total Points: X
+
+Next steps:
+  - Run /ace:refine-story E1-F1-S1 to prepare for execution
+  - Add stories to sprint with /ace:sprint-plan
+```
+
+</ace-plan-feature>

package/commands/ace-plan-project.md

@@ -0,0 +1,205 @@
+# /ace:plan-project - Plan Your Project
+
+Collaboratively plan your project by defining epics, features, and high-level architecture.
+
+## Usage
+
+```
+/ace:plan-project [project-description]
+```
+
+### Arguments
+
+- `project-description` - Optional: A brief description of what you want to build
+
+## Behavior
+
+This command guides you through a structured project planning session that produces:
+- Defined epics (large bodies of work)
+- Features within each epic
+- Initial technical architecture considerations
+- Prioritized backlog ready for sprint planning
+
+## Instructions for Claude
+
+<ace-plan-project>
+
+### Prerequisites Check
+
+1. Verify ACE is initialized by checking for `.ace/config.json`
+2. If not initialized, prompt user to run `/ace:init` first
+3. Read current PROJECT.md and BACKLOG.md if they exist
+
+### Phase 1: Project Understanding
+
+Start by understanding the project. Ask these questions conversationally (not all at once):
+
+1. **What are you building?**
+   - Get a clear understanding of the product/feature
+   - Clarify the target users
+   - Understand the core problem being solved
+
+2. **What does success look like?**
+   - Define measurable outcomes
+   - Identify key milestones
+
+3. **What are the constraints?**
+   - Timeline expectations
+   - Technical constraints (existing stack, integrations)
+   - Team/resource constraints
+
+### Phase 2: Epic Discovery
+
+Based on the project understanding, collaboratively identify epics.
+
+**Guide the user through epic discovery:**
+
+```
+An epic is a large body of work that:
+- Takes multiple sprints to complete
+- Delivers significant user value when done
+- Can be broken into 3-8 features
+
+Let's identify the major epics for your project.
+```
+
+For each epic, capture:
+- **ID**: E1, E2, E3...
+- **Name**: Clear, descriptive name
+- **Description**: What this epic delivers
+- **User Value**: Why this matters to users
+- **Dependencies**: Other epics this depends on
+
+Create epic files in `.ace/backlog/`:
+
+```markdown
+<!-- .ace/backlog/E1-epic-name.md -->
+# E1: Epic Name
+
+## Description
+<What this epic delivers>
+
+## User Value
+<Why this matters to users>
+
+## Dependencies
+<Other epics this depends on, if any>
+
+## Features
+<!-- Added by /ace:plan-epic -->
+| ID | Feature | Status |
+|----|---------|--------|
+| - | - | - |
+
+## Acceptance Criteria
+- [ ] <Criteria 1>
+- [ ] <Criteria 2>
+
+## Status
+- **State:** Draft
+- **Priority:** <High/Medium/Low>
+- **Created:** <timestamp>
+```
+
+### Phase 3: Feature Identification
+
+For each epic, identify high-level features (don't go deep yet):
+
+```
+A feature is a piece of deliverable functionality that:
+- Can be completed in 1-2 sprints
+- Provides standalone value
+- Can be demonstrated to users
+```
+
+Capture features briefly:
+- **ID**: E1-F1, E1-F2...
+- **Name**: Feature name
+- **Epic**: Parent epic
+- **Brief description**: One line
+
+### Phase 4: Priority & Sequencing
+
+Help the user prioritize:
+
+1. **Identify MVP epics** - What's the minimum to launch?
+2. **Sequence epics** - What order makes sense?
+3. **Identify risks** - What's most uncertain?
+
+Create a prioritized view in BACKLOG.md.
+
+### Phase 5: Update Project Files
+
+Update the following files with gathered information:
+
+**PROJECT.md** - Add/update:
+- Vision section
+- Goals section
+- Success criteria
+
+**BACKLOG.md** - Add:
+- All epics in priority order
+- Features identified for each epic
+
+**STATE.md** - Add:
+- Any decisions made during planning
+- Context notes for future sessions
+
+### Phase 6: GitHub Integration (if enabled)
+
+If GitHub is enabled in config:
+
+1. Create epic issues with `ace:epic` label:
+```bash
+gh issue create --title "E1: Epic Name" --body "..." --label "ace:epic"
+```
+
+2. Create a project board or milestone (ask user preference)
+
+### Output Summary
+
+After planning, output:
+
+```
+✓ Project planning complete!
+
+Epics Created:
+  E1: <Epic Name> - <status>
+  E2: <Epic Name> - <status>
+  ...
+
+Features Identified: <count>
+
+Updated Files:
+  - PROJECT.md
+  - BACKLOG.md
+  - STATE.md
+  - .ace/backlog/E1-*.md
+  - .ace/backlog/E2-*.md
+
+Recommended Next Steps:
+  1. Review and refine PROJECT.md
+  2. Run /ace:plan-epic E1 to detail your first epic
+  3. Run /ace:plan-feature to break features into stories
+```
+
+### Planning Principles
+
+Throughout the planning session, apply these principles:
+
+1. **Start broad, narrow later** - Don't over-detail early
+2. **User value focus** - Every epic should deliver user value
+3. **Vertical slices** - Prefer end-to-end features over horizontal layers
+4. **Dependencies minimize** - Reduce coupling between epics
+5. **Risk early** - Tackle uncertain/risky work first
+6. **Keep it agile** - Plans will change, that's okay
+
+### Conversation Style
+
+- Be collaborative, not prescriptive
+- Ask clarifying questions
+- Offer suggestions but let user decide
+- Summarize understanding before moving to next phase
+- Keep the energy high - planning should be exciting!
+
+</ace-plan-project>

package/commands/ace-plan-story.md

@@ -0,0 +1,97 @@
+# /ace:plan-story - Plan a Story
+
+Create a new user story with detailed acceptance criteria and technical breakdown.
+
+## Usage
+
+```
+/ace:plan-story <feature-id> "<story-title>"
+/ace:plan-story E1-F1 "User can log in with email"
+```
+
+### Arguments
+
+- `feature-id` - The parent feature identifier
+- `story-title` - Title for the new story
+
+## Behavior
+
+This command creates a new story with:
+- User story format (As a... I want... So that...)
+- Detailed acceptance criteria
+- Technical implementation notes
+- Task breakdown for execution
+
+## Instructions for Claude
+
+<ace-plan-story>
+
+### Prerequisites
+
+1. Verify ACE is initialized
+2. Verify parent feature exists
+3. Determine next story ID
+
+### Planning Flow
+
+1. **Gather Story Details**
+   - Who is the user?
+   - What do they want to accomplish?
+   - What benefit does this provide?
+
+2. **Define Acceptance Criteria**
+   - Given/When/Then format preferred
+   - Should be testable
+   - Cover happy path and edge cases
+
+3. **Technical Breakdown**
+   - Identify files that need changes
+   - Note any new dependencies
+   - Consider testing approach
+
+4. **Create Story File**
+
+```markdown
+# E1-F1-S1: Story Title
+
+## User Story
+
+As a [type of user],
+I want [goal/desire],
+So that [benefit/value].
+
+## Acceptance Criteria
+
+- [ ] Given [context], when [action], then [outcome]
+- [ ] Given [context], when [action], then [outcome]
+- [ ] Edge case: [description]
+
+## Technical Notes
+
+### Files to Modify
+- `path/to/file.ts` - [what changes]
+
+### New Dependencies
+- None
+
+### Testing Approach
+- Unit tests for [components]
+- Integration test for [flow]
+
+## Tasks
+
+<!-- Added by /ace:refine-story -->
+
+## Metadata
+
+- **Status:** Draft
+- **Points:** [1-8]
+- **Sprint:** None
+- **Created:** <timestamp>
+```
+
+5. **GitHub Integration** (if enabled)
+   - Create issue with story template
+   - Link to parent feature issue
+
+</ace-plan-story>