omgkit 2.26.1 → 2.27.0

package/README.md

@@ -88,7 +88,37 @@ OMGKIT brings agile methodology to AI-assisted development:
 - **Sprints**: Time-boxed development cycles
 - **AI Team**: Autonomous execution with human oversight
 
-### 4. Testing Automation (New)
+### 4. Reference-Aware Planning (New)
+
+Use PRDs, specs, and design documents to inform sprint planning:
+
+```bash
+# Create sprint with PRD reference
+/sprint:sprint-new "Auth Sprint" --ref=.omgkit/artifacts/prd-auth.md
+
+# Sprint with multiple references
+/sprint:sprint-new "Payment" --ref=artifacts/prd.md,specs/api.yaml
+
+# Sprint with AI proposal based on references
+/sprint:sprint-new "MVP" --propose --ref=.omgkit/artifacts/
+```
+
+Configure in `.omgkit/workflow.yaml`:
+
+```yaml
+references:
+  enabled: true
+  auto_suggest: true
+  max_tokens: 10000
+  extract_sections:
+    - requirements
+    - user_stories
+    - acceptance_criteria
+```
+
+References automatically propagate to `/sprint:team-run` and `/sprint:backlog-add`.
+
+### 5. Testing Automation
 
 OMGKIT includes a comprehensive testing automation system:
 
@@ -349,6 +379,13 @@ Commands are slash-prefixed actions organized by namespace.
 /sprint:team-status     # Show team activity
 ```
 
+**Reference-Aware Planning** (available on sprint commands):
+```bash
+/sprint:sprint-new "Auth" --ref=artifacts/prd.md     # Sprint with PRD context
+/sprint:team-run --ref=specs/api.yaml                # Add refs during execution
+/sprint:backlog-add "Login" --ref=artifacts/prd.md   # Task with ref context
+```
+
 ### Autonomous Development (`/auto:*`)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgkit",
-  "version": "2.26.1",
+  "version": "2.27.0",
   "description": "Omega-Level Development Kit - AI Team System for Claude Code. 41 agents, 160 commands, 161 skills, 69 workflows.",
   "keywords": [
     "claude-code",

package/plugin/commands/sprint/backlog-add.md

@@ -1,21 +1,108 @@
 ---
-description: Add task to backlog
+description: Add task to backlog with optional reference context
 allowed-tools: Read, Write
-argument-hint: <task> [--type TYPE] [--priority N]
+argument-hint: <task> [--type TYPE] [--priority N] [--ref=<path>]
+references:
+  supported: true
+  inherit_from_sprint: true
+  types: [file, folder, glob]
+related_skills:
+  - autonomous/project-orchestration
+  - methodology/agile-sprint
+related_commands:
+  - /sprint:sprint-new
+  - /sprint:backlog-show
+  - /sprint:backlog-prioritize
 ---
 
-# ➕ Backlog Add: $ARGUMENTS
+# Backlog Add: $ARGUMENTS
 
-Add task to backlog.
+Add a task to the backlog with optional reference context.
 
 ## Options
-- `--type` - feature, bugfix, docs, test, refactor, infra
-- `--priority` - 1-5 (1 = highest)
 
-## Example
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--type` | Task type | `--type feature` |
+| `--priority` | Priority 1-5 (1 = highest) | `--priority 1` |
+| `--ref=<path>` | Reference source for task context | `--ref=artifacts/prd.md#auth` |
+| `--req=<id>` | Link to requirement ID | `--req=REQ-001` |
+
+### Task Types
+
+| Type | Description | Auto-generates Tests |
+|------|-------------|---------------------|
+| `feature` | New functionality | Yes |
+| `bugfix` | Bug fix | Yes (regression) |
+| `docs` | Documentation | No |
+| `test` | Test task | No |
+| `refactor` | Code refactoring | Yes |
+| `infra` | Infrastructure | No |
+
+## Reference Options
+
+The `--ref` parameter allows linking tasks to specific reference documents:
+
+```bash
+# Link task to PRD requirement
+/backlog:add "User login" --type feature --ref=artifacts/prd.md
+
+# Link to specific section (anchor)
+/backlog:add "OAuth flow" --ref=artifacts/prd.md#authentication
+
+# Link to API spec
+/backlog:add "Payment endpoint" --ref=specs/api-payment.yaml
 ```
-/backlog:add "Add user authentication" --type feature --priority 1
+
+### Requirement Linking
+
+Use `--req` to link tasks directly to requirement IDs:
+
+```bash
+/backlog:add "User authentication" --type feature --req=REQ-AUTH-001
 ```
 
+This enables:
+- Traceability from requirements to implementation
+- Coverage tracking for requirements
+- Impact analysis for requirement changes
+
 ## Output
-Generates task ID and saves to `.omgkit/sprints/backlog.yaml`
+
+Generates task ID and saves to `.omgkit/sprints/backlog.yaml`:
+
+```yaml
+backlog:
+  - id: TASK-042
+    title: "User login"
+    type: feature
+    priority: 1
+    status: pending
+    reference:
+      source: "artifacts/prd.md"
+      requirement_id: "REQ-AUTH-001"
+    created: 2025-01-07
+```
+
+## Examples
+
+```bash
+# Basic task
+/backlog:add "Add user authentication" --type feature --priority 1
+
+# Task with reference
+/backlog:add "Implement OAuth" --type feature --ref=artifacts/prd-auth.md
+
+# Task linked to requirement
+/backlog:add "Rate limiting" --type feature --req=REQ-API-005
+
+# Task with all options
+/backlog:add "Payment gateway" --type feature --priority 1 --ref=specs/api.yaml --req=REQ-PAY-001
+```
+
+## Best Practices
+
+1. **Link to requirements** - Use `--req` for traceability
+2. **Reference specs** - Use `--ref` for implementation context
+3. **Set appropriate type** - Enables correct test generation
+4. **Prioritize consistently** - 1 = critical, 5 = nice-to-have

package/plugin/commands/sprint/sprint-new.md

@@ -1,24 +1,101 @@
 ---
-description: Create new sprint
+description: Create new sprint with optional reference sources
 allowed-tools: Task, Read, Write, Grep, Glob
-argument-hint: "[name] [--propose]"
+argument-hint: "[name] [--propose] [--ref=<path>]"
+references:
+  supported: true
+  types: [file, folder, glob]
+  default_paths:
+    - ".omgkit/artifacts/"
+related_skills:
+  - autonomous/project-orchestration
+  - methodology/agile-sprint
+related_commands:
+  - /sprint:sprint-start
+  - /sprint:team-run
+  - /sprint:backlog-add
 ---
 
-# 🏃 Sprint New: $ARGUMENTS
+# Sprint New: $ARGUMENTS
 
-Create new sprint.
+Create a new sprint with optional reference sources for context-aware planning.
 
 ## Options
-- `--propose` - AI analyzes codebase and proposes tasks
 
-## AI Proposal Analyzes
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--propose` | AI analyzes codebase and proposes tasks | `--propose` |
+| `--ref=<path>` | Reference source(s) for planning context | `--ref=artifacts/prd.md` |
+
+## Reference Options
+
+The `--ref` parameter allows you to specify reference sources that provide context for sprint planning:
+
+### Single File Reference
+```bash
+/sprint:sprint-new "Auth Sprint" --ref=.omgkit/artifacts/prd-auth.md
+```
+
+### Multiple Files Reference
+```bash
+/sprint:sprint-new "Payment Sprint" --ref=artifacts/prd.md,specs/api.yaml
+```
+
+### Folder Reference (all files)
+```bash
+/sprint:sprint-new "MVP Sprint" --ref=.omgkit/artifacts/
+```
+
+### Glob Pattern Reference
+```bash
+/sprint:sprint-new "API Sprint" --ref="specs/*.yaml"
+```
+
+## Reference Types
+
+| Type | File Patterns | Extracted Sections |
+|------|---------------|-------------------|
+| PRD | `**/prd*.md`, `**/requirements*.md` | Requirements, User Stories, Acceptance Criteria |
+| Spec | `**/spec*.md`, `**/technical*.md` | Technical specs, Architecture |
+| OpenAPI | `**/*.yaml`, `**/*.yml` | Endpoints, Schemas |
+| Design | `**/design*.md` | UI/UX flows, Mockups |
+
+## How References Work
+
+```
+/sprint:sprint-new "Feature X" --ref=artifacts/prd.md
+                    ↓
+┌─────────────────────────────────────────────────────────┐
+│  1. Load Reference Sources                              │
+│     └── Read artifacts/prd.md                           │
+│                                                          │
+│  2. Extract Relevant Sections                           │
+│     ├── Requirements                                    │
+│     ├── User Stories                                    │
+│     ├── Acceptance Criteria                             │
+│     └── Technical Constraints                           │
+│                                                          │
+│  3. Inject into Planning Context                        │
+│     └── AI plans with full context                      │
+│                                                          │
+│  4. Store Reference in Sprint                           │
+│     └── sprint.yaml includes ref sources                │
+└─────────────────────────────────────────────────────────┘
+```
+
+## AI Proposal Analysis (with --propose)
+
+When using `--propose`, AI analyzes:
+
 - TODOs and FIXMEs in code
 - Test coverage gaps
 - Documentation gaps
 - Features aligned with vision
 - Technical debt
+- **Reference documents** (when --ref provided)
 
 ## Output
+
 Save to: `.omgkit/sprints/current.yaml`
 
 ```yaml
@@ -27,5 +104,46 @@ sprint:
   status: planning
   start_date: null
   end_date: null
+
+  # Reference sources (when --ref used)
+  references:
+    - source: ".omgkit/artifacts/prd-auth.md"
+      type: prd
+      sections: [requirements, stories, acceptance]
+
   tasks: []
 ```
+
+## Context Propagation
+
+References set in sprint are automatically propagated to:
+
+- `/sprint:team-run` - Agents receive reference context
+- `/sprint:backlog-add` - New tasks can inherit sprint refs
+- `/dev:feature` - Implementation aligned with specs
+
+## Examples
+
+```bash
+# Basic sprint without references
+/sprint:sprint-new "Sprint 1"
+
+# Sprint with AI-proposed tasks
+/sprint:sprint-new "MVP Sprint" --propose
+
+# Sprint with PRD reference
+/sprint:sprint-new "Auth Sprint" --ref=.omgkit/artifacts/prd-auth.md
+
+# Sprint with multiple references and AI proposal
+/sprint:sprint-new "Payment Sprint" --propose --ref=artifacts/prd.md,specs/api.yaml
+
+# Sprint with entire artifacts folder
+/sprint:sprint-new "Full Feature" --ref=.omgkit/artifacts/
+```
+
+## Best Practices
+
+1. **Use specific references** - Point to relevant documents, not entire folders
+2. **Combine with --propose** - Let AI analyze refs and propose aligned tasks
+3. **Keep artifacts updated** - Reference docs should reflect current requirements
+4. **Link tasks to requirements** - Use `requirement_ref` in tasks for traceability

package/plugin/commands/sprint/team-run.md

@@ -1,13 +1,19 @@
 ---
 description: Run AI team on sprint tasks with configurable test enforcement
 allowed-tools: Task, Read, Write, Bash, Grep, Glob
-argument-hint: "[--mode MODE] [--no-test] [--test-level LEVEL]"
+argument-hint: "[--mode MODE] [--no-test] [--test-level LEVEL] [--ref=<path>]"
+references:
+  supported: true
+  inherit_from_sprint: true
+  types: [file, folder, glob]
 related_skills:
   - methodology/test-enforcement
   - methodology/test-task-generation
   - omega/omega-sprint
+  - autonomous/project-orchestration
 related_commands:
   - /sprint:team-status
+  - /sprint:sprint-new
   - /quality:verify-done
   - /quality:coverage-check
 testing:
@@ -44,6 +50,24 @@ This command respects project testing configuration from `.omgkit/workflow.yaml`
 | `--no-test` | Skip test enforcement (soft mode only) | `/sprint:team-run --no-test` |
 | `--test-level <level>` | Override enforcement level | `/sprint:team-run --test-level strict` |
 | `--with-test` | Force test enforcement | `/sprint:team-run --with-test` |
+| `--ref=<path>` | Additional reference sources | `/sprint:team-run --ref=specs/api.yaml` |
+
+### Reference Options
+
+The `--ref` parameter provides additional context for task execution:
+
+```bash
+# Use sprint references (inherited automatically)
+/sprint:team-run
+
+# Add additional references for this run
+/sprint:team-run --ref=docs/architecture.md
+
+# Override sprint references
+/sprint:team-run --ref=specs/api-v2.yaml
+```
+
+**Reference Inheritance**: By default, team-run inherits references from the current sprint. Use `--ref` to add or override.
 
 ### Enforcement Levels
 

package/templates/config.yaml

@@ -36,6 +36,60 @@ output:
   artifacts_dir: .omgkit/artifacts
   verbose: false
 
+# Reference settings
+references:
+  # Enable reference loading in sprints and commands
+  enabled: true
+
+  # Auto-suggest relevant artifacts when planning
+  auto_suggest: true
+
+  # Default paths to search for references
+  default_paths:
+    - ".omgkit/artifacts/"
+    - "docs/"
+
+  # Maximum tokens to include from references
+  max_tokens: 10000
+
+  # File type mappings for smart extraction
+  type_mappings:
+    prd:
+      patterns:
+        - "**/prd*.md"
+        - "**/requirements*.md"
+        - "**/product*.md"
+      sections:
+        - requirements
+        - user_stories
+        - acceptance_criteria
+    spec:
+      patterns:
+        - "**/spec*.md"
+        - "**/technical*.md"
+        - "**/architecture*.md"
+      sections:
+        - overview
+        - api
+        - data_model
+    openapi:
+      patterns:
+        - "**/*.yaml"
+        - "**/*.yml"
+        - "**/openapi.*"
+      sections:
+        - paths
+        - components
+    design:
+      patterns:
+        - "**/design*.md"
+        - "**/ui*.md"
+        - "**/ux*.md"
+      sections:
+        - flows
+        - components
+        - interactions
+
 # MCP settings
 mcp:
   context7: true

package/templates/omgkit/workflow.yaml

@@ -176,3 +176,46 @@ feature_flags:
 
   # Default state for new flags
   default_state: false
+
+# =============================================================================
+# REFERENCE-AWARE PLANNING
+# =============================================================================
+references:
+  # Enable reference loading in sprints
+  enabled: true
+
+  # Auto-suggest relevant artifacts when creating sprints
+  auto_suggest: true
+
+  # Maximum tokens for reference content (prevent context overflow)
+  max_tokens: 10000
+
+  # Section extraction settings for PRD/spec files
+  extract_sections:
+    - requirements
+    - user_stories
+    - acceptance_criteria
+    - constraints
+    - api_endpoints
+
+  # Propagate references to child commands
+  propagation:
+    # Pass sprint refs to team-run
+    to_team_run: true
+
+    # Pass sprint refs to individual tasks
+    to_tasks: true
+
+    # Pass refs to feature/fix commands
+    to_dev_commands: true
+
+  # Reference validation
+  validation:
+    # Check if referenced files exist
+    check_exists: true
+
+    # Warn if references are outdated (modified after sprint creation)
+    check_freshness: true
+
+    # Maximum file age in days before warning
+    max_age_days: 30