opencode-athena 0.9.0 → 0.10.0

package/README.md

@@ -230,6 +230,77 @@ Todo sync is enabled by default. To disable:
 }
 ```
 
+## Story Complexity Analysis
+
+Athena automatically checks story complexity before implementation and suggests decomposition when stories are too large. This prevents context compaction issues during implementation.
+
+### How It Works
+
+When you run `/athena-dev`, Athena:
+
+1. **Analyzes the story** - Counts tasks, estimates effort points per task
+2. **Compares against thresholds** - Research-backed limits (8 tasks / 8 points warning, 12 tasks / 13 points critical)
+3. **Recommends action** - `proceed`, `suggest-decomposition`, or `require-decomposition`
+4. **Offers decomposition** - Automatically groups tasks and creates sub-stories
+
+### Effort Estimation
+
+Each task is scored based on:
+
+| Signal | Points Added |
+|--------|--------------|
+| Many subtasks (>5) | +3 |
+| High-effort keywords (implement, create, refactor) | +2 |
+| Medium-effort keywords (add, update, modify) | +1 |
+| Testing/verification required | +1 |
+| External system integration (API, database) | +1 |
+| Vague description | +2 |
+
+Points are mapped to Fibonacci scale: 1, 2, 3, 5, 8.
+
+### Decomposition
+
+When decomposition is recommended, Athena:
+
+1. **Groups tasks by concern** - UI, core logic, integration, testing
+2. **Balances groups** - Target ~8 points per sub-story
+3. **Handles dependencies** - Testing tasks depend on implementation tasks
+4. **Preserves dev notes** - Applicable sections copied to each sub-story
+
+**Filename format:**
+- Original: `3-2-reset-list-screen.md`
+- Sub-stories: `3-2a-reset-list-screen.md`, `3-2b-reset-list-screen.md`
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `athena_analyze_story` | Analyze story complexity and get recommendations |
+| `athena_decompose_story` | Split story into sub-stories |
+
+### Example Output
+
+```
+📊 COMPLEXITY ANALYSIS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Tasks: 10 / 8 recommended                    ⚠️
+Points: 15 / 8 threshold                     🔴
+File size: 12KB / 30KB                       ✅
+Estimated compactions: 1
+
+🔀 SUGGESTED DECOMPOSITION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Story 3.2a: Core Implementation
+├─ Tasks: 1, 2, 3, 4
+├─ Points: ~8
+└─ Dependencies: None
+
+Story 3.2b: Testing & Verification
+├─ Tasks: 5, 6, 7
+├─ Points: ~7
+└─ Dependencies: 3.2a
+```
+
 ## Configuration
 
 Configuration files are stored in `~/.config/opencode/`:

package/commands/athena-dev.md

@@ -4,6 +4,25 @@ description: Implement the current BMAD story using Sisyphus and specialized sub
 
 # Athena Dev - Story Implementation
 
+## Instructions
+
+You receive: `$ARGUMENTS`
+
+**Parse the argument and load the story:**
+
+1. **If argument is provided** (e.g., "4.5", "story-4-5", "docs/stories/story-4-5.md"):
+   - Call `athena_get_story({ storyId: "<argument>" })`
+   - The tool handles all formats: story IDs, file paths, and `@` references
+   - **Proceed immediately** with Step 0 (Complexity Check) after loading
+
+2. **If no argument provided**:
+   - Call `athena_get_story()` to load the next ready story
+   - **Proceed immediately** with Step 0 (Complexity Check) after loading
+
+**Do NOT ask clarifying questions about which story to implement. Load it and start working.**
+
+---
+
 ## Git Operations Policy
 
 **⚠️ AUTOMATIC GIT OPERATIONS ARE PROHIBITED**
@@ -33,7 +52,7 @@ I've completed the implementation. Would you like me to:
 ```
 athena_update_status({
   storyId: "X.Y",
-  status: "completed",
+  status: "done",
   completionSummary: "What was implemented..."
 })
 ```
@@ -42,29 +61,112 @@ This updates sprint-status.yaml without requiring git commits.
 
 ---
 
-You are implementing a BMAD story using OpenCode Athena's full capabilities.
+## Step 0: Complexity Check (Before Implementation)
 
-**You are Sisyphus, the orchestrator.** You will coordinate subagents and tools to implement this story efficiently and correctly.
+**After loading the story, check if it's too large to implement comfortably.**
 
-## Step 1: Load Story Context
+Call **athena_analyze_story** to assess complexity:
+
+```
+athena_analyze_story({ storyId: "<story ID from Step 1>" })
+```
+
+This returns:
+- **Metrics**: Task count, subtasks, file size
+- **Effort estimates**: Points per task with signals (API calls, state mgmt, etc.)
+- **Recommendation**: `proceed`, `suggest-decomposition`, or `require-decomposition`
+- **Suggested splits**: If decomposition recommended
+
+### If recommendation is `proceed`:
+
+Continue with **Step 1.5** (Sync Todos) and normal implementation.
+
+### If recommendation is `suggest-decomposition`:
+
+Present the analysis to the user:
+
+```
+📊 STORY COMPLEXITY ANALYSIS
+
+This story has {X} tasks totaling ~{Y} story points.
+Research suggests stories >8 points often cause context compaction issues.
+
+SUGGESTED DECOMPOSITION:
+{show the suggested splits}
+
+What would you like to do?
+[D] Decompose into sub-stories (recommended)
+[P] Proceed with full story anyway
+[M] Modify the decomposition groupings
+```
 
-Call **athena_get_story** to load the current story context:
+**If user chooses [D] (Decompose):**
+```
+athena_decompose_story({ 
+  storyId: "<story ID>",
+  useSuggestedSplits: true,
+  confirmed: true 
+})
+```
 
+Then load the first sub-story:
 ```
-athena_get_story()
+athena_get_story({ storyId: "<returned nextStory>" })
 ```
 
-If you need a specific story, pass the story ID:
+**If user chooses [P] (Proceed):**
+Continue with normal implementation, but warn:
+> ⚠️ This story may require multiple compactions. Progress will be preserved via todo sync.
 
+**If user chooses [M] (Modify):**
+Work with the user to adjust task groupings, then call:
 ```
-athena_get_story({ storyId: "2.3" })
+athena_decompose_story({
+  storyId: "<story ID>",
+  splits: [
+    { suffix: "a", taskIds: ["1", "2"], title: "Custom title" },
+    { suffix: "b", taskIds: ["3", "4", "5"] }
+  ],
+  confirmed: true
+})
 ```
 
-This returns:
+### If recommendation is `require-decomposition`:
+
+**Do NOT proceed without decomposition.** The story is too large.
+
+```
+🚫 STORY TOO LARGE
+
+This story has {X} tasks totaling ~{Y} story points.
+Stories this size consistently cause implementation problems.
+
+Decomposition is REQUIRED before implementation.
+
+{show the suggested splits}
+
+[D] Decompose into sub-stories
+[M] Modify the decomposition groupings
+```
+
+Wait for user decision before proceeding.
+
+---
+
+You are implementing a BMAD story using OpenCode Athena's full capabilities.
+
+**You are Sisyphus, the orchestrator.** You will coordinate subagents and tools to implement this story efficiently and correctly.
+
+## Step 1: Load Story Context
+
+**Note:** Story loading happens in the Instructions section above. This step documents what `athena_get_story` returns for reference.
+
+`athena_get_story()` returns:
 - **Story**: Requirements and acceptance criteria
 - **Architecture**: Relevant technical patterns and decisions
 - **PRD**: Relevant functional requirements
 - **Sprint progress**: Where this story fits in the overall sprint
+- **Todos**: Pre-formatted task list for `todowrite`
 
 **CRITICAL: Check for Implementation Notes from Previous Review**
 
@@ -109,13 +211,14 @@ This means `/athena-review` was run previously and findings were discussed with
 ### If No Implementation Notes Exist:
 
 This is a **fresh implementation** - proceed with the normal workflow:
-- Understand requirements and acceptance criteria
-- Plan your approach (Step 2)
-- Implement the story (Step 3)
-- Verify implementation (Step 4)
-- Complete the story (Step 5)
+- Step 0: Check complexity (already done above)
+- Step 1.5: Sync todos from story
+- Step 2: Plan your approach
+- Step 3: Implement the story
+- Step 4: Verify implementation
+- Step 5: Complete the story
 
-## Step 1.5: Sync Todos (Automatic)
+## Step 1.5: Sync Todos
 
 When `athena_get_story` returns, it includes a `todos` section with BMAD tasks formatted for the todo list.
 
@@ -342,7 +445,7 @@ When implementation is verified and ready, update the status:
 ```
 athena_update_status({
   storyId: "<story ID>",
-  status: "completed",
+  status: "done",
   completionSummary: "Implemented {feature}. {What was built}. {Tests status}. {Any notes}."
 })
 ```
@@ -365,7 +468,7 @@ If the story isn't complete but you need to save progress:
 ```
 athena_update_status({
   storyId: "<story ID>",
-  status: "in_progress",
+  status: "in-progress",
   notes: "Progress: {what's done}. Remaining: {what's left}."
 })
 ```
@@ -392,6 +495,10 @@ Your workflow as Sisyphus:
 
 ```
 1. Load story (athena_get_story)
+0. Check complexity (athena_analyze_story)
+   - If too large → decompose first
+   - If manageable → proceed
+1.5. Sync todos (todowrite)
 2. Plan approach:
    - @explore → Find similar code in codebase
    - @librarian → Research unfamiliar tech

package/commands/athena-status.md

@@ -61,7 +61,7 @@ When you begin implementing a story:
 ```
 athena_update_status({
   storyId: "2.4",
-  status: "in_progress"
+  status: "in-progress"
 })
 ```
 
@@ -77,7 +77,7 @@ When implementation is done and verified:
 ```
 athena_update_status({
   storyId: "2.4",
-  status: "completed",
+  status: "done",
   completionSummary: "Implemented OAuth2 login flow with Google and GitHub providers. Added token refresh mechanism. All tests passing."
 })
 ```
@@ -126,7 +126,7 @@ When ready for code review or QA:
 ```
 athena_update_status({
   storyId: "2.4",
-  status: "needs_review"
+  status: "review"
 })
 ```
 
@@ -149,21 +149,21 @@ athena_update_status({
 ┌──────────────────────────────────────────────────────────────┐
 │  2. START IMPLEMENTATION                                      │
 │     /athena-dev → Load story, plan, implement                │
-│     Status: pending → in_progress                            │
+│     Status: backlog → in-progress                            │
 └──────────────────────────────────────────────────────────────┘
                             │
                             ▼
 ┌──────────────────────────────────────────────────────────────┐
 │  3. QUALITY GATE (Optional but Recommended)                   │
 │     /athena-review → Oracle code review + adversarial review │
-│     Status: in_progress → needs_review → completed/in_progress│
+│     Status: in-progress → review → done/in-progress          │
 └──────────────────────────────────────────────────────────────┘
                             │
                             ▼
 ┌──────────────────────────────────────────────────────────────┐
 │  4. COMPLETE & NEXT                                           │
 │     /athena-status → Verify completion, see next story       │
-│     Status: in_progress → completed                          │
+│     Status: in-progress → done                               │
 └──────────────────────────────────────────────────────────────┘
                             │
                             ▼
@@ -186,31 +186,32 @@ athena_update_status({
 ### Valid Status Flow
 
 ```
-pending ──────┬─────────────────────────────────────────┐
+backlog ──────┬─────────────────────────────────────────┐
               │                                          │
               ▼                                          │
-         in_progress ◄──────────────────────────┐       │
+         in-progress ◄──────────────────────────┐       │
               │                                  │       │
               ├──────► blocked ─────────────────┘       │
               │            │                            │
               │            └────────────────────────────┘
               │                 (when unblocked)
               │
-              ├──────► needs_review ────────────┐
+              ├──────► review ──────────────────┐
               │                                  │
               │                                  ▼
-              └──────────────────────────► completed
+              └──────────────────────────────► done
 ```
 
 ### Status Definitions
 
 | Status | Meaning | Next Actions |
 |--------|---------|--------------|
-| **pending** | Not yet started | Start with `/athena-dev` |
-| **in_progress** | Actively being worked on | Continue implementation |
+| **backlog** | Not yet started | Start with `/athena-dev` |
+| **ready-for-dev** | Reviewed and ready for implementation | Start with `/athena-dev` |
+| **in-progress** | Actively being worked on | Continue implementation |
 | **blocked** | Waiting for external dependency | Resolve blocker, then resume |
-| **needs_review** | Ready for review | Run `/athena-review` |
-| **completed** | Done and verified | Move to next story |
+| **review** | Ready for review | Run `/athena-review` |
+| **done** | Done and verified | Move to next story |
 
 ## Handling Special Cases
 
@@ -222,8 +223,8 @@ If you return to a story after a break:
 # Check current state
 athena_get_story()
 
-# If status is in_progress, continue
-# If status is pending, start fresh with /athena-dev
+# If status is in-progress, continue
+# If status is backlog or ready-for-dev, start fresh with /athena-dev
 ```
 
 ### Story Dependencies
@@ -245,7 +246,7 @@ When a blocker is resolved:
 ```
 athena_update_status({
   storyId: "2.4",
-  status: "in_progress",
+  status: "in-progress",
   notes: "Blocker resolved. Received API credentials from DevOps. Resuming implementation."
 })
 ```
@@ -257,7 +258,7 @@ If issues are found after marking complete:
 ```
 athena_update_status({
   storyId: "2.4",
-  status: "in_progress",
+  status: "in-progress",
   notes: "Reopened: Found edge case not covered. Need to add handling for empty input."
 })
 ```
@@ -274,7 +275,7 @@ When reviewing sprint status, watch for:
 
 ### Warning Signs
 - ⚠️ Multiple stories blocked
-- ⚠️ Story in_progress for too long
+- ⚠️ Story in-progress for too long
 - ⚠️ No progress for extended time
 - ⚠️ Blockers not getting resolved
 
@@ -283,7 +284,7 @@ When reviewing sprint status, watch for:
 | Warning | Action |
 |---------|--------|
 | Multiple blocked stories | Escalate blockers, prioritize resolution |
-| Story stuck in_progress | Break into smaller tasks, ask for help |
+| Story stuck in-progress | Break into smaller tasks, ask for help |
 | No progress | Check for hidden blockers, reassess scope |
 | Blockers aging | Follow up with responsible parties |
 

package/dist/cli/index.js

@@ -1011,10 +1011,10 @@ z.object({
   )
 });
 z.object({
-  storyId: z.string().describe("The story ID (e.g., '2.3')"),
-  status: z.enum(["in_progress", "completed", "blocked", "needs_review"]).describe("The new status for the story"),
+  storyId: z.string().describe("The story ID (e.g., '2.3' or '2-3')"),
+  status: z.enum(["in-progress", "review", "done", "blocked"]).describe("The new status for the story (BMAD v6 hyphenated format)"),
   notes: z.string().optional().describe("Notes about the status change (required for 'blocked' status)"),
-  completionSummary: z.string().optional().describe("Summary of what was implemented (required for 'completed' status)")
+  completionSummary: z.string().optional().describe("Summary of what was implemented (required for 'done' status)")
 });
 z.object({
   includeArchitecture: z.boolean().optional().default(true),
@@ -1030,6 +1030,41 @@ z.object({
   key: z.string().optional().describe("Configuration key (dot notation, e.g., 'bmad.autoStatusUpdate')"),
   value: z.unknown().optional().describe("Value to set (for 'set' action)")
 });
+var BmadStoryStatusEnum = z.enum([
+  "backlog",
+  "ready-for-dev",
+  "in-progress",
+  "review",
+  "done",
+  "blocked"
+]);
+z.enum(["backlog", "in-progress", "done"]);
+z.enum(["optional", "done"]);
+var BmadDevelopmentStatusEnum = z.enum([
+  "backlog",
+  "ready-for-dev",
+  "in-progress",
+  "review",
+  "done",
+  "blocked",
+  "optional"
+]);
+z.object({
+  generated: z.string().optional(),
+  project: z.string().optional(),
+  project_key: z.string().optional(),
+  tracking_system: z.string().optional(),
+  story_location: z.string().optional(),
+  current_story: z.string().nullable().optional(),
+  last_modified: z.string().optional(),
+  development_status: z.record(z.string(), BmadDevelopmentStatusEnum)
+});
+z.object({
+  storyId: z.string().describe("The story ID (e.g., '2.3' or '2-3')"),
+  status: BmadStoryStatusEnum.describe("The new status for the story"),
+  notes: z.string().optional().describe("Notes about the status change (required for 'blocked')"),
+  completionSummary: z.string().optional().describe("Summary of implementation (required for 'done')")
+});
 var StoryStatusEnum = z.enum([
   "pending",
   "in_progress",
@@ -1038,11 +1073,12 @@ var StoryStatusEnum = z.enum([
   "needs_review"
 ]);
 z.enum([
-  "pending",
-  "in_progress",
-  "completed",
+  "backlog",
+  "ready-for-dev",
+  "in-progress",
+  "review",
+  "done",
   "blocked",
-  "needs_review",
   "loading"
 ]);
 z.object({