ai-eng-system 0.0.10 → 0.0.12

package/README.md

@@ -4,6 +4,31 @@ Advanced development tools with context engineering, research orchestration, and
 
 ## 🚀 Quick Start
 
+### Spec-Driven Development (Recommended)
+
+This toolkit follows the **spec-driven development methodology** from GitHub's official blog post: [Spec-driven development with AI: Get started with a new open source toolkit](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/).
+
+**The 5-Phase Workflow** (always in this order):
+
+```mermaid
+flowchart LR
+    A[🎯 Research] --> B[📋 Specify] --> C[📝 Plan] --> D[🔨 Work] --> E[🔍 Review]
+    D -.->|If changes needed| E
+    E -.->|Repeat| D
+```
+
+| Phase | Command | Output |
+|-------|---------|--------|
+| 1. Research | `/ai-eng/research` | Context and findings |
+| 2. Specify | `/ai-eng/specify` | Feature specification |
+| 3. Plan | `/ai-eng/plan` | Implementation plan |
+| 4. Work | `/ai-eng/work` | Quality-gated code |
+| 5. Review | `/ai-eng/review` | Multi-agent approval |
+
+This approach ensures specifications are your "source of truth" for what gets built, reducing guesswork and enabling more reliable AI-assisted development.
+
+See [docs/spec-driven-workflow.md](./docs/spec-driven-workflow.md) for complete workflow guide with examples.
+
 ### Claude Code (Recommended)
 ```bash
 /plugin marketplace add v1truv1us/ai-eng-system
@@ -22,11 +47,21 @@ Advanced development tools with context engineering, research orchestration, and
 ```
 ## 📋 What's Included
 
-### Commands (16 total)
-- `/ai-eng/plan` - Create detailed implementation plans
-- `/ai-eng/review` - Multi-perspective code review (29 agents)
-- `/ai-eng/seo` - SEO audits with Core Web Vitals
-- `/ai-eng/work` - Execute plans with quality gates
+### Spec-Driven Development Workflow
+
+**Core workflow for systematic development** (always research → specify → plan → work → review):
+
+| Phase | Command | Purpose |
+|-------|---------|---------|
+| 1. Research | `/ai-eng/research` | Multi-phase research with codebase and external context |
+| 2. Specify | `/ai-eng/specify` | Create feature specifications with TCRO framework |
+| 3. Plan | `/ai-eng/plan` | Create detailed implementation plans from specs |
+| 4. Work | `/ai-eng/work` | Execute plans with quality gates and validation |
+| 5. Review | `/ai-eng/review` | Multi-perspective code review (29 agents) |
+
+> **Methodology**: Based on [GitHub's spec-driven development approach](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
+
+### Additional Commands (12 total)
 - `/ai-eng/optimize` - Prompt enhancement (+45% quality)
 - `/ai-eng/deploy` - Pre-deployment checklists
 - `/ai-eng/compound` - Document solved problems
@@ -36,9 +71,11 @@ Advanced development tools with context engineering, research orchestration, and
 - `/ai-eng/create-command` - AI-assisted command generation
 - `/ai-eng/create-skill` - AI-assisted skill creation
 - `/ai-eng/create-tool` - AI-assisted custom tool creation
-- `/ai-eng/research` - Multi-phase research orchestration
 - `/ai-eng/context` - Context management and retrieval
 - `/ai-eng/clean` - Remove build artifacts and generated files
+- `/ai-eng/seo` - SEO audits with Core Web Vitals
+
+**Total Commands**: 17
 
 ### Agents (29 total)
 - **Architecture & Planning**: `architect-advisor`, `backend-architect`, `infrastructure-builder`
@@ -163,4 +200,10 @@ Commands reference specialized agents automatically:
 /ai-eng/review --agent=backend-architect  # Architecture review
 ```
 
-**Built with research-backed prompting techniques** (+45-115% quality improvement)
+**Built with research-backed prompting techniques** (+45-115% quality improvement)
+
+## 📖 Workflow Guide
+
+For complete documentation on the **Research → Specify → Plan → Work → Review** workflow, see:
+- **[docs/spec-driven-workflow.md](./docs/spec-driven-workflow.md)** - Visual workflow guide with examples
+- **[docs/research-command-guide.md](./docs/research-command-guide.md)** - Research command deep dive

package/dist/.claude-plugin/commands/optimize.md

@@ -94,6 +94,44 @@ EXAMPLES:
 3. **Quality Evaluation**: Identify areas for improvement (clarity, performance, effectiveness)
 4. **Research Planning**: Determine best sources and techniques to apply
 
+### Phase 1.5: Prompt Refinement (for --prompt mode)
+
+When `--prompt` flag is used:
+
+Use skill: `prompt-refinement`
+Phase: [auto-detect or specified]
+
+The prompt-refinement skill provides:
+- TCRO structuring (Task, Context, Requirements, Output)
+- Phase-specific clarifying questions (research, specify, plan, work)
+- Integration with incentive-prompting techniques
+
+**Workflow:**
+1. Load prompt-refinement skill
+2. Detect phase based on prompt content or explicit `--phase` flag
+3. Apply phase-specific template (research, specify, plan, or work)
+4. Structure prompt into TCRO format
+5. Enhance with incentive-prompting techniques
+6. Present refined prompt for user confirmation
+
+**Example:**
+```bash
+# User provides vague prompt
+/ai-eng/optimize "help me debug auth" --prompt
+
+# System:
+1. Invokes prompt-refinement skill
+2. Detects "work" phase (debugging)
+3. Loads work.md template
+4. Asks clarifying questions:
+   - What error are you seeing?
+   - Where in the flow does it happen?
+   - What's your tech stack?
+5. Structures into TCRO format
+6. Applies expert persona, stakes language, step-by-step reasoning
+7. Presents refined prompt for approval
+```
+
 ### Phase 2: Research & Best Practices
 Based on type and sources, research:
 
@@ -102,6 +140,7 @@ Based on type and sources, research:
 - **OpenAI Guides**: Prompt engineering for GPT models
 - **OpenCode/Crush**: Community-tested optimization patterns
 - **Academic Research**: Latest papers on prompt optimization
+- **prompt-refinement skill**: TCRO framework and phase-specific templates
 
 #### For Code
 - **Language-Specific**: Performance patterns for target language

package/dist/.claude-plugin/commands/plan.md

@@ -1,6 +1,6 @@
 ---
 name: ai-eng/plan
-description: Create a detailed implementation plan for a feature
+description: Create a detailed implementation plan for a feature with spec-driven support
 agent: plan
 ---
 
@@ -12,15 +12,17 @@ Create a structured, atomic implementation plan for: $ARGUMENTS
 
 ```bash
 /ai-eng/plan [description] [options]
+/ai-eng/plan --from-spec=<path> [options]
 ```
 
 ### Options
 
+- `--from-spec <path>`: Load specification from file (e.g., `specs/auth/spec.md`)
 - `--swarm`: Use Swarms multi-agent orchestration instead of legacy coordinator
 - `-s, --scope <scope>`: Plan scope (architecture|implementation|review|full) [default: full]
 - `-r, --requirements <reqs...>`: List of specific requirements
 - `-c, --constraints <constraints...>`: List of constraints to consider
-- `-o, --output <file>`: Output plan file [default: generated-plan.yaml]
+- `-o, --output <file>`: Output plan file [default: `specs/[feature]/plan.md`]
 - `-v, --verbose`: Enable verbose output
 
 ## Planning Philosophy
@@ -31,9 +33,35 @@ Create a structured, atomic implementation plan for: $ARGUMENTS
 - Are testable in isolation
 - Don't require context from unfinished sibling tasks
 
+**Spec-Driven**: When specification exists, plan is derived from spec requirements:
+- Each user story maps to one or more tasks
+- All spec acceptance criteria must be covered by plan
+- Non-functional requirements become technical constraints
+
 ## Process
 
-### Phase 1: Discovery (Research Mode)
+### Phase 0: Prompt Refinement
+Use skill: `prompt-refinement`
+Phase: `plan`
+
+[The prompt-refinement skill will transform your input into a structured TCRO format by asking clarifying questions about task, context, requirements, and output format.]
+
+### Phase 1: Load Specification (if exists)
+
+If `--from-spec` flag is provided:
+1. **Read specification** from `specs/[feature]/spec.md`
+2. **Extract user stories** and their acceptance criteria
+3. **Extract non-functional requirements** (security, performance, etc.)
+4. **Identify open questions** marked with `[NEEDS CLARIFICATION]`
+5. **Use as foundation** for technical planning
+
+If no spec is found:
+- Warn user: "No specification found. Consider running `/ai-eng/specify` first to create a detailed specification."
+- Offer: "Proceed with inline requirements gathering? (y/n)"
+- If yes, gather requirements through clarifying questions
+- If no, exit and prompt user to run `/ai-eng/specify`
+
+### Phase 2: Discovery (Research Mode)
 
 #### Subagent Communication Protocol (Minimal)
 
@@ -44,8 +72,10 @@ Use:
 ```text
 <CONTEXT_HANDOFF_V1>
 Goal: (1 sentence)
-Constraints: (bullets)
-Files / folders to focus: (bullets)
+Scope: (codebase|docs|external|all)
+Known constraints: (bullets; optional)
+What I already checked: (bullets; optional)
+Files/paths to prioritize: (bullets; optional)
 Deliverable: (what you must return)
 Output format: RESULT_V1
 </CONTEXT_HANDOFF_V1>
@@ -57,7 +87,7 @@ And require:
 <RESULT_V1>
 RESULT:
 EVIDENCE:
-RISKS:
+OPEN_QUESTIONS:
 NEXT_STEPS:
 CONFIDENCE: 0.0-1.0
 </RESULT_V1>
@@ -80,7 +110,32 @@ CONFIDENCE: 0.0-1.0
    - Identify integration points with existing code
    - Flag potential breaking changes
 
-### Phase 2: Task Decomposition
+### Phase 3: Technical Planning
+
+#### From Specification (if exists)
+
+For each user story in spec:
+1. **Map to technical tasks**: Break user story into implementation tasks
+2. **Define acceptance criteria**: Derive from spec acceptance criteria
+3. **Apply technical constraints**: From spec's non-functional requirements
+
+Example mapping:
+```markdown
+**User Story**: US-001 User Registration
+→ Task REG-001: Create User database model
+→ Task REG-002: Implement registration API endpoint
+→ Task REG-003: Add email validation
+→ Task REG-004: Implement password hashing
+```
+
+#### Inline Requirements (if no spec)
+
+If proceeding without specification:
+- Use clarifying questions to gather requirements
+- Define technical approach
+- Document assumptions and constraints
+
+### Phase 4: Task Decomposition
 
 Break the feature into **atomic tasks** using this hierarchy:
 
@@ -100,10 +155,82 @@ Epic (the full feature)
 | Depends On | Blocking task IDs | `FEAT-001-B` (or "None") |
 | Files | Exact files to modify/create | `src/context/session.ts` |
 | Acceptance Criteria | Checkboxes that define "done" | `[ ] Class exports correctly` |
+| Spec Reference | Links to user story/acceptance criteria | `US-001: AC-2` |
 | Estimated Time | Time box | `30 min` |
 | Complexity | Low / Medium / High | `Medium` |
 
-### Phase 3: Risk Assessment
+### Phase 5: Generate Supporting Artifacts
+
+Based on feature type and technical approach, generate:
+
+#### data-model.md (if database involved)
+
+```markdown
+# Data Model
+
+## Entities
+
+### User
+```typescript
+{
+  id: string (UUID, primary key)
+  email: string (unique, indexed)
+  password_hash: string (bcrypt)
+  created_at: timestamp
+  updated_at: timestamp
+}
+```
+
+## Relationships
+
+- User has many Sessions
+- Session belongs to User
+
+## Indexes
+
+- `users_email_unique` on (email) for uniqueness
+- `users_created_at` for sorting
+```
+
+#### contracts/ (if API involved)
+
+```markdown
+# API Contracts
+
+## POST /api/auth/register
+
+**Request:**
+```json
+{
+  "email": "user@example.com",
+  "password": "securePassword123"
+}
+```
+
+**Response (201 Created):**
+```json
+{
+  "success": true,
+  "user_id": "uuid-here"
+}
+```
+
+**Response (400 Bad Request):**
+```json
+{
+  "error": "Invalid email format"
+}
+```
+```
+
+#### research.md (if technical decisions needed)
+
+Document decisions made during planning:
+- Technology choices with rationale
+- Trade-offs considered
+- Alternatives evaluated
+
+### Phase 6: Risk Assessment
 
 For each phase, identify:
 
@@ -111,7 +238,7 @@ For each phase, identify:
 |------|--------|------------|------------|
 | (risk description) | High/Med/Low | High/Med/Low | (strategy) |
 
-### Phase 4: Testing Strategy
+### Phase 7: Testing Strategy
 
 Define testing approach for each phase:
 
@@ -120,32 +247,48 @@ Define testing approach for each phase:
 - **Manual Testing**: What scenarios to validate?
 - **Regression Checks**: What existing functionality could break?
 
-### Phase 5: SEO & Performance Considerations
-
-If applicable:
-- Core Web Vitals impact
-- Bundle size changes
-- API response times
-- Caching strategies
+**Spec-driven validation**: Ensure all spec acceptance criteria have corresponding tests
 
 ## Output Format
 
-### File: `plans/[YYYY-MM-DD]-[feature-slug].md`
+### Directory: `specs/[feature-name]/`
+
+```
+specs/[feature-name]/
+├── spec.md              # From /ai-eng/specify (if exists)
+├── plan.md              # Implementation plan (this file)
+├── tasks.md             # Task breakdown (optional separate file)
+├── data-model.md         # Data schemas (if applicable)
+├── research.md           # Technical research (if applicable)
+└── contracts/            # API contracts (if applicable)
+    ├── api-spec.json
+    └── signalr-spec.md
+```
+
+### File: `specs/[feature-name]/plan.md`
 
 ```markdown
 # [Feature Name] Implementation Plan
 
 **Status**: Draft | In Progress | Complete
 **Created**: [date]
+**Specification**: specs/[feature-name]/spec.md (if exists)
 **Estimated Effort**: [hours/days]
 **Complexity**: Low | Medium | High
 
 ## Overview
-[2-3 sentence summary]
+[2-3 sentence summary of technical approach]
 
-## Success Criteria
-- [ ] [Measurable outcome 1]
-- [ ] [Measurable outcome 2]
+## Specification Reference
+
+[If spec exists, summarize user stories and their technical mapping]
+
+### User Stories → Tasks Mapping
+
+| User Story | Tasks | Status |
+|-------------|--------|--------|
+| US-001 | TASK-001, TASK-002 | Pending |
+| US-002 | TASK-003 | Pending |
 
 ## Architecture
 [Diagram or description of component relationships]
@@ -158,12 +301,14 @@ If applicable:
 ### Task 1.1: [Task Title]
 - **ID**: FEAT-001-A
 - **Depends On**: None
-- **Files**: 
+- **User Story**: US-001 (if from spec)
+- **Files**:
   - `path/to/file.ts` (modify)
   - `path/to/new-file.ts` (create)
 - **Acceptance Criteria**:
   - [ ] Criterion 1
   - [ ] Criterion 2
+  - [ ] Spec AC: [Link to spec acceptance criteria]
   - [ ] Tests pass
 - **Time**: 30 min
 - **Complexity**: Low
@@ -186,17 +331,58 @@ If applicable:
 ### Unit Tests
 - [ ] Test for [component]
 
-### Integration Tests  
+### Integration Tests
 - [ ] Test [interaction]
 
+### Spec Validation
+- [ ] All user stories have corresponding tasks
+- [ ] All spec acceptance criteria are covered by task acceptance criteria
+- [ ] Non-functional requirements are implemented
+
 ## Rollback Plan
 [How to revert if something goes wrong]
 
 ## References
-- [Link to relevant docs]
+- [Link to specification] (if exists)
+- [Link to research findings]
 - [Link to similar implementations]
 ```
 
+### Optional: Separate tasks.md
+
+If tasks.md is generated separately:
+
+```markdown
+# [Feature Name] Tasks
+
+## Task List
+
+### PRIORITY TRACK - Can execute in parallel
+- [ ] TASK-001
+- [ ] TASK-002
+
+### TRACK - After PRIORITY TRACK completes
+- [ ] TASK-003
+- [ ] TASK-004
+
+## Task Details
+
+### TASK-001: [Task Title]
+**ID**: TASK-001
+**User Story**: US-001
+**Depends On**: None
+**Estimated**: 30 min
+**Status**: Pending | In Progress | Complete
+
+#### Acceptance Criteria
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+#### Files
+- `file1.ts` (create)
+- `file2.ts` (modify)
+```
+
 ## Post-Planning Actions
 
 After generating the plan:
@@ -205,6 +391,7 @@ After generating the plan:
 2. **Create GitHub issue** (optional) - Link to plan file
 3. **Estimate total effort** - Sum of all task estimates
 4. **Identify parallel tracks** - Tasks without dependencies that can run concurrently
+5. **Validate spec coverage** (if spec exists) - Ensure all spec requirements are covered
 
 ## Tips for Effective Plans
 
@@ -213,3 +400,77 @@ After generating the plan:
 - **Checkpoints**: Each phase should end with a working (possibly incomplete) state
 - **Escape hatches**: Note where you could stop and still have value
 - **Evidence-based**: Include file paths and code snippets from discovery
+- **Spec-driven**: Ensure all spec acceptance criteria have corresponding task acceptance criteria
+
+## Integration
+
+### Feeds Into
+- `/ai-eng/work` - Reads plan.md for task execution
+- Validates task completion against spec.md acceptance criteria
+
+### Reads From
+- `specs/[feature]/spec.md` - User stories, acceptance criteria, NFRs
+- `CLAUDE.md` - Project philosophy and constraints
+- `docs/research/*.md` - Optional research context
+
+## Example Usage
+
+### Example 1: Plan from Existing Spec
+
+```bash
+# User provides feature name (spec already exists)
+/ai-eng/plan --from-spec=specs/auth
+
+# Step 0: Prompt refinement skill asks planning-specific questions
+# Step 1: Loads spec from specs/auth/spec.md
+# Step 2: Maps user stories to technical tasks
+# Step 3: Generates plan.md, data-model.md, contracts/
+# Step 4: Validates spec coverage
+```
+
+### Example 2: Plan Without Spec (Inline)
+
+```bash
+# User provides description without spec
+/ai-eng/plan "implement JWT-based authentication"
+
+# Step 0: Prompt refinement asks planning questions
+# Step 1: Warns about missing spec, offers to proceed
+# Step 2: Gathers requirements through clarification
+# Step 3: Generates plan.md
+```
+
+## Best Practices
+
+### Spec-Driven Planning
+
+When specification exists:
+1. **Map each user story to tasks**: Don't miss any requirements
+2. **Trace acceptance criteria**: Each spec AC should have task AC
+3. **Document decisions**: Why specific tech choices were made
+4. **Mark dependencies**: Which tasks must come before others
+
+### Cross-Reference
+
+Always cross-reference between artifacts:
+- Tasks reference user stories (US-001)
+- Acceptance criteria reference spec acceptance criteria (AC-2)
+- Data models reference user story requirements
+
+### Task Independence
+
+Ensure tasks are truly atomic:
+- Can you complete it without touching unfinished sibling tasks?
+- Is it testable in isolation?
+- Does it have clear start and end states?
+
+## Success Criteria
+
+Successful planning achieves:
+- ✅ All tasks are atomic and independently completable
+- ✅ Dependencies are clearly documented
+- ✅ All spec acceptance criteria are covered (if spec exists)
+- ✅ Supporting artifacts generated (data-model, contracts)
+- ✅ Risk assessment completed
+- ✅ Testing strategy defined
+- ✅ Ready to feed into `/ai-eng/work`

package/dist/.claude-plugin/commands/research.md

@@ -33,6 +33,9 @@ outputs:
 
 Conduct comprehensive research for: $ARGUMENTS
 
+> **Phase 1 of Spec-Driven Workflow**: Research → Specify → Plan → Work → Review  
+> See: [GitHub's spec-driven development methodology](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)
+
 ## Usage
 
 ```bash
@@ -47,8 +50,17 @@ Conduct comprehensive research for: $ARGUMENTS
 - `-o, --output <file>`: Output file path
 - `-f, --format <format>`: Export format (markdown|json|html) [default: markdown]
 - `--no-cache`: Disable research caching
+- `--feed-into <command>`: After research, invoke specified command with research context (specify|plan)
 - `-v, --verbose`: Enable verbose output
 
+## Process
+
+### Phase 0: Prompt Refinement
+Use skill: `prompt-refinement`
+Phase: `research`
+
+[The prompt-refinement skill will transform your input into a structured TCRO format by asking clarifying questions about research scope, sources, depth, and deliverable format.]
+
 ## Expert Context
 
 You are a senior research analyst with 15+ years of experience at companies like Google, Stripe, and Netflix. Your expertise is in systematic investigation, pattern recognition, and synthesizing complex information into actionable insights. This research is critical to the project's success.
@@ -196,4 +208,33 @@ Save research document to `docs/research/[date]-[topic-slug].md`
 
 Rate your confidence in the research findings (0-1) and identify any assumptions or limitations.
 
+## Integration
+
+### Feeds Into
+- `/ai-eng/specify` - Use `--feed-into=specify` to pass research findings to specification phase
+- `/ai-eng/plan` - Use `--feed-into=plan` to pass research findings directly to planning
+
+### Feed-Into Workflow
+
+When `--feed-into` is used:
+
+1. **Save research document** to standard location
+2. **Load research findings** as context for target command
+3. **Pass research path** to target command automatically
+
+Example:
+```bash
+# Research that feeds into specification
+/ai-eng/research "authentication patterns" --feed-into=specify
+
+# This:
+# 1. Completes research phase
+# 2. Saves to docs/research/[date]-auth-patterns.md
+# 3. Automatically invokes /ai-eng/specify --from-research=docs/research/[date]-auth-patterns.md
+```
+
+The target command will receive the research findings in its context, eliminating the need to manually copy-paste research results.
+
+Rate your confidence in the research findings (0-1) and identify any assumptions or limitations.
+
 $ARGUMENTS