opencode-athena 0.0.1 → 0.1.0

package/README.md

@@ -72,14 +72,39 @@ Load SM agent → *sprint-planning → *create-story
 
 ### 2. Implement with Athena (Phase 4)
 
-Use Athena bridge commands:
+Use Athena bridge commands in an iterative loop:
 
 ```
 /athena-dev        # Load story, implement with Sisyphus
-/athena-review     # Quality gate
+/athena-review     # Quality gate with collaborative discussion
+```
+
+**If review passes:**
+```
 /athena-status     # Mark complete, get next story
 ```
 
+**If review finds issues:**
+1. Sisyphus auto-updates story status to `in_progress`
+2. You discuss findings together and decide which to address
+3. Sisyphus updates story file with implementation notes
+4. Sisyphus recommends: **Stay in session** or **Restart `/athena-dev`**
+5. You decide and proceed:
+   - **Stay in session**: Continue fixing in current session
+   - **Restart**: Exit and run `/athena-dev` again (loads implementation notes)
+6. After fixes, run `/athena-review` again (respects previous decisions)
+
+**Iterative Quality Loop:**
+```
+Implement → Review → Discuss → Fix → Review → ... → PASS
+```
+
+**Key Features:**
+- Review discussions are preserved in story file
+- Subsequent reviews don't re-block on deferred/rejected items
+- Checkboxed implementation notes track progress
+- Flexible: stay in session for simple fixes, restart for complex rework
+
 ### 3. Repeat
 
 Continue until sprint is complete, then run retrospective with BMAD SM.
@@ -165,6 +190,96 @@ Common issues:
 | BMAD not found | Run `npx bmad-method@alpha install` in your project |
 | Commands not available | Verify commands are in `~/.config/opencode/command/` |
 
+## Publishing Releases
+
+This package uses **Trusted Publishing (OIDC)** for secure, credential-free releases via GitHub Actions.
+
+### For Maintainers: Creating a New Release
+
+1. **Update version:**
+   ```bash
+   npm version patch  # 0.0.3 -> 0.0.4
+   npm version minor  # 0.1.0 -> 0.2.0
+   npm version major  # 1.0.0 -> 2.0.0
+   ```
+
+2. **Commit and push:**
+   ```bash
+   git add package.json
+   git commit -m "Bump version to X.Y.Z"
+   git push origin main
+   ```
+
+3. **Create and push tag:**
+   ```bash
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
+
+4. **Monitor:** GitHub Actions publishes automatically
+   - Watch: [Actions](https://github.com/ZebulonRouseFrantzich/opencode-athena/actions)
+   - Verify: [npm package](https://www.npmjs.com/package/opencode-athena)
+   - Check: [GitHub Releases](https://github.com/ZebulonRouseFrantzich/opencode-athena/releases)
+
+### Security Features
+
+**Trusted Publishing (OIDC):**
+- ✅ Zero stored credentials (no npm tokens in GitHub)
+- ✅ Short-lived authentication (hours, not years)
+- ✅ Cannot be leaked (runtime-only tokens)
+- ✅ Automatic provenance attestations
+- ✅ OpenSSF industry standard
+
+**Provenance Attestations:**
+
+Every release includes cryptographically signed provenance via [Sigstore](https://www.sigstore.dev/), providing:
+- Verifiable link between npm package and GitHub source code
+- Proof of which GitHub Actions workflow built the package
+- Immutable transparency log entry
+- Supply chain security guarantees
+
+**Verify any published version:**
+```bash
+npm install opencode-athena
+npm audit signatures
+```
+
+### CI/CD Configuration
+
+The release workflow uses:
+- **Trusted Publishing** - OIDC authentication (no long-lived tokens)
+- **npm CLI 11+** - Required for Trusted Publishing support
+- **GitHub-hosted runners** - Secure, isolated build environment
+- **Automatic provenance** - Generated without `--provenance` flag
+
+Trusted Publisher configuration:
+- **Provider:** GitHub Actions
+- **Repository:** `ZebulonRouseFrantzich/opencode-athena`
+- **Workflow:** `release.yml`
+- **Permissions:** `id-token: write`, `contents: write`
+
+### Troubleshooting Releases
+
+| Issue | Solution |
+|-------|----------|
+| "Unable to authenticate" | Verify Trusted Publisher config on npmjs.com matches exactly (case-sensitive) |
+| Workflow filename mismatch | Must be `release.yml` (not `Release.yml` or full path) |
+| npm version error | Ensure npm 11.5.1+ (workflow upgrades automatically) |
+| No provenance generated | Automatic with Trusted Publishing - check npmjs.com package page |
+| Self-hosted runner error | Use GitHub-hosted runners only (required for OIDC) |
+
+For detailed setup: [`.github/workflows/release.yml`](.github/workflows/release.yml)
+
+### Why Trusted Publishing?
+
+We use Trusted Publishing instead of traditional npm tokens because:
+- **Security:** Eliminates risks from npm credential breaches
+- **Compliance:** Implements OpenSSF Trusted Publishers standard
+- **Simplicity:** No manual token management or rotation
+- **Transparency:** Automatic provenance provides supply chain visibility
+
+Learn more: [npm Trusted Publishing Documentation](https://docs.npmjs.com/trusted-publishers)
+
 ## Credits
 
 Built on top of:

package/commands/athena-dev.md

@@ -28,6 +28,55 @@ This returns:
 - **PRD**: Relevant functional requirements
 - **Sprint progress**: Where this story fits in the overall sprint
 
+**CRITICAL: Check for Implementation Notes from Previous Review**
+
+After loading the story, check if the story file contains an **Implementation Notes** section.
+
+### If Implementation Notes Exist:
+
+This means `/athena-review` was run previously and findings were discussed with the user.
+
+**What to do:**
+1. **Read the Implementation Notes section carefully** - It contains:
+   - **Findings to Address**: Checkboxed list of fixes the user agreed to implement
+   - **Deferred to Future Work**: Items the user decided not to fix now
+   - **Not Implemented**: Items the user decided not to implement at all
+
+2. **Prioritize the "Findings to Address" items** - These are your PRIMARY work items for this session
+
+3. **Check off items as you complete them**:
+   - Use the Read tool to load the story file
+   - Use the Edit tool to change `- [ ]` to `- [x]` for completed items
+   - This provides progress tracking
+
+4. **Respect the decisions**:
+   - DO NOT work on items marked as "Deferred" or "Not Implemented"
+   - These represent user decisions from the review discussion
+   - Focus only on agreed fixes
+
+5. **Verify your fixes**:
+   - Run `lsp_diagnostics` on changed files after each fix
+   - When all checkboxes are complete, run `/athena-review` again to verify
+
+**Your approach with Implementation Notes:**
+```
+1. Load story context (athena_get_story)
+2. Review implementation notes
+3. Work through checkboxed items systematically
+4. Check off completed items
+5. Verify with lsp_diagnostics
+6. When done, recommend running /athena-review
+```
+
+### 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 2: Plan Your Approach
 
 Before diving into code, plan your implementation strategy:

package/commands/athena-review.md

@@ -22,6 +22,20 @@ This returns:
 - Relevant PRD sections
 - Sprint context
 
+**CRITICAL: Check for Previous Review Decisions**
+
+After loading the story, check if the story file contains an **Implementation Notes** section from a previous review. This section will be present if `/athena-review` was run before and findings were discussed.
+
+If **Implementation Notes exist**:
+- Extract the **Deferred to Future Work** items
+- Extract the **Not Implemented** items
+- These represent USER DECISIONS from previous reviews
+- You MUST NOT re-raise these issues in the current review
+- Only flag NEW issues or issues the user agreed to fix
+
+If **No Implementation Notes exist**:
+- This is the first review - proceed normally with all findings
+
 ## Step 2: Identify Changed Files
 
 Use git to identify what files were modified for this story:
@@ -245,6 +259,20 @@ Capture test results.
 
 **After receiving both Oracle reviews and automated check results**, synthesize a unified quality gate report.
 
+**CRITICAL: Filter Against Previous Decisions**
+
+Before generating the report, if Implementation Notes exist from Step 1:
+
+1. **Load previous decisions** from the story file's Implementation Notes section
+2. **Extract deferred/not-implemented items** (exact descriptions or keywords)
+3. **Filter Oracle findings**:
+   - EXCLUDE any finding that matches items marked as "Deferred to Future Work"
+   - EXCLUDE any finding that matches items marked as "Not Implemented"
+   - INCLUDE only NEW findings or items the user agreed to fix
+4. **Note filtered items**: If you filter out findings, mention this in the report: "X findings excluded (previously deferred/rejected in prior review)"
+
+This ensures you don't re-block the story on issues the user has already made decisions about.
+
 Generate this structured report:
 
 ```markdown
@@ -368,12 +396,14 @@ Generate this structured report:
 3. Re-run quality gate after critical fixes
 ```
 
-## Step 7: Update Story Status
+## Step 7: Discuss Findings and Update Story
 
-Based on the Quality Gate Decision:
+Based on the Quality Gate Decision, take different actions:
 
 ### If PASS (no critical issues, no blockers, LSP clean, build/tests pass):
 
+Auto-update status to completed:
+
 ```
 athena_update_status({
   storyId: "{storyId}",
@@ -382,24 +412,257 @@ athena_update_status({
 })
 ```
 
-### If FAIL (critical issues OR blockers OR LSP errors OR build/test failures):
+Congratulate the user and move on.
+
+### If FAIL or NEEDS WORK (issues found after filtering):
+
+Follow this collaborative process:
+
+**Step 7a: Update Status to In Progress**
+
+First, immediately update the story status:
 
 ```
 athena_update_status({
   storyId: "{storyId}",
   status: "in_progress",
-  notes: "Quality gate FAILED. Must fix: {count} critical issues, {count} blockers, {count} LSP errors. See quality gate report above. Re-run /athena-review after fixes."
+  notes: "Quality gate completed. Found {count} critical issues, {count} blockers, {count} warnings, {count} gaps. Awaiting user input on which findings to address."
 })
 ```
 
-### If NEEDS WORK (warnings/gaps but no critical issues):
+**Step 7b: Discuss Findings with User**
+
+Present the findings collaboratively (remember: already filtered against previous decisions):
 
 ```
-athena_update_status({
-  storyId: "{storyId}",
-  status: "needs_review",
-  notes: "Quality gate: NEEDS WORK. Critical issues resolved, but {count} warnings and {count} gaps found. Recommend addressing before completion. See quality gate report above."
-})
+I've completed the quality gate review for Story {storyId}. Here's what I found:
+
+**Critical Issues**: {count}
+{list each with file/line if available}
+
+**Blockers**: {count}
+{list each with scenario that would fail}
+
+**Warnings & Gaps**: {count}
+{list each with severity}
+
+**Automated Checks**:
+- LSP Errors: {count}
+- Build: {PASS/FAIL}
+- Tests: {PASS/FAIL}
+
+{if previous review existed}
+Note: {X} findings from Oracle were excluded because you previously decided to defer or not implement them.
+{endif}
+
+**My Assessment**:
+
+**Must Fix** (blocks story completion):
+- {item 1}
+- {item 2}
+...
+
+**Should Fix** (significantly improves quality):
+- {item 1}
+- {item 2}
+...
+
+**Optional** (nice-to-have):
+- {item 1}
+- {item 2}
+...
+
+Let's discuss:
+1. Which findings do you want to address in this story?
+2. Are there any findings you want to defer to future work?
+3. Are there any findings you disagree with or want to mark as "Not Implemented"?
+
+Once we agree on scope, I'll update the story file with implementation notes.
+```
+
+**Wait for user response before proceeding to Step 7c.**
+
+**Step 7c: Update Story File with Implementation Notes**
+
+After the user has decided which findings to address, update the story file.
+
+If this is the **first review** (no Implementation Notes section exists):
+
+Append this section to the story file at `docs/stories/story-{epic}-{number}.md`:
+
+```markdown
+## Implementation Notes
+
+### Quality Review - {current date and time}
+
+**Findings to Address:**
+- [ ] {Finding description} - Priority: Critical - File: {file}:{line}
+- [ ] {Finding description} - Priority: High - File: {file}:{line}
+- [ ] {Finding description} - Priority: Medium
+
+**Deferred to Future Work:**
+- {Finding description} - Reason: {user's reason} - Target: {Epic X, Story Y if mentioned}
+
+**Not Implemented:**
+- {Finding description} - Reason: {user's reason - e.g., "Out of scope", "Disagree with finding", "Accepted risk"}
+
+**Review Conducted By**: Sisyphus + Oracle (Code Review + Adversarial Review)  
+**Automated Checks**: LSP: {result}, Build: {result}, Tests: {result}
+```
+
+If this is a **subsequent review** (Implementation Notes section already exists):
+
+**Preserve the previous review notes** and append a new section:
+
+```markdown
+### Quality Review - {current date and time} (Follow-up Review)
+
+**Previous Review Status:**
+- {X} items were addressed from previous review
+- {Y} items remain in progress
+- {Z} items remain deferred
+
+**New Findings to Address:**
+- [ ] {New finding} - Priority: {level}
+
+**Additional Deferred Items:**
+- {Finding description} - Reason: {user's reason}
+
+**Additional Not Implemented Items:**
+- {Finding description} - Reason: {user's reason}
+
+**Review Conducted By**: Sisyphus + Oracle  
+**Automated Checks**: LSP: {result}, Build: {result}, Tests: {result}
+```
+
+Use the Read tool to load the story file, then use the Edit tool to append these notes.
+
+**Step 7d: Recommend Approach (Stay in Session vs Restart)**
+
+After updating the story file, analyze the situation and recommend an approach to the user:
+
+Evaluate:
+1. **Fix Complexity**: Are the fixes simple (type errors, minor logic) or complex (architectural changes)?
+2. **Fix Scope**: How many files need changes? How many lines?
+3. **Session Health**: Is the current session reasonably sized or bloated with context?
+4. **Fix Type**: Bug fixes vs refactoring vs new features?
+
+Then provide a recommendation:
+
+```
+I've updated the story file with our agreed implementation notes.
+
+**My Recommendation**: {Stay in Current Session / Start Fresh Session}
+
+{if recommending STAY IN SESSION}:
+**Reasoning**:
+- The fixes are straightforward: {brief explanation}
+- Estimated changes: {X files, Y lines, simple/moderate complexity}
+- Current session context is valuable and not too bloated
+- Estimated fix time: {rough estimate based on complexity}
+- Benefits: Maintain context, efficient iteration
+
+**Shall I proceed with the fixes in this session?**
+
+{if recommending START FRESH SESSION}:
+**Reasoning**:
+- The fixes require: {architectural changes / major refactoring / cross-cutting concerns}
+- Estimated changes: {X files, Y lines, high complexity}
+- Current session is {too long / context-heavy / would benefit from fresh start}
+- Benefits: Clean context, better planning, clearer focus
+
+**I recommend:**
+1. Exit this session
+2. Run `/athena-dev` to reload the story (it will pick up the implementation notes)
+3. Implement the fixes with a clear strategy
+4. Run `/athena-review` again when complete
+
+**What would you like to do?**
+
+{always provide options}:
+1. **Continue in this session** - I'll start fixing the items now
+2. **Exit and restart `/athena-dev`** - Fresh session approach
+3. **Something else** - Discuss further or modify the plan
+```
+
+**Wait for user decision before proceeding.**
+
+## Step 8: Execute Based on User Decision
+
+After presenting your recommendation in Step 7d, the user will choose one of the following paths:
+
+### Path A: User Chooses to Continue in Current Session
+
+If the user wants to proceed with fixes in the current session:
+
+```
+Great, I'll proceed with the fixes in this session.
+
+I'll work through the implementation notes systematically:
+{list the checkboxed items from the story file}
+
+As I complete each fix, I'll check it off in the story file.
+
+When all fixes are complete, I'll run `/athena-review` again to verify the quality gate passes.
+```
+
+Then:
+1. Work through each item in the "Findings to Address" list
+2. Use the Read tool to check off completed items (convert `- [ ]` to `- [x]`)
+3. Run `lsp_diagnostics` on changed files
+4. When all items are checked off, inform the user and recommend running `/athena-review` again
+
+### Path B: User Chooses to Exit and Restart
+
+If the user wants to start a fresh session:
+
+```
+Understood. The story file has been updated with implementation notes at:
+`docs/stories/story-{epic}-{number}.md`
+
+The implementation notes detail exactly what needs to be fixed based on our discussion.
+
+When you run `/athena-dev` again:
+- Sisyphus will automatically load these implementation notes
+- The notes will guide the fix implementation
+- After fixes are complete, run `/athena-review` again
+
+The sprint status remains at 'in_progress' until the quality gate passes.
+
+Good luck with the fixes!
+```
+
+Then end the session.
+
+### Path C: User Wants to Defer All Fixes or Make Other Changes
+
+If the user wants to modify the plan or defer all work:
+
+```
+I understand you want to {take a different approach}.
+
+Options:
+1. **Modify the implementation notes** - We can adjust what's in "Findings to Address" vs "Deferred"
+2. **Mark story as blocked** - If waiting on external dependencies
+3. **Keep as in_progress** - Come back to this later
+4. **Mark complete despite findings** - (Not recommended, but your choice)
+
+What would you like to do?
+```
+
+Then follow the user's guidance and update the story status accordingly using `athena_update_status`.
+
+### Re-running the Review
+
+When `/athena-review` is run again after fixes:
+- Step 1 will load the implementation notes
+- Step 6 will filter out previously deferred/not-implemented items
+- Only NEW issues or unfixed items will be flagged
+- If all agreed fixes are complete and no new issues found → PASS
+
+This creates an iterative loop:
+```
+Review → Discuss → Fix → Review → Discuss → Fix → ... → PASS
 ```
 
 ## Important Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-athena",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Strategic wisdom meets practical execution - Unified oh-my-opencode + BMAD METHOD toolkit for OpenCode",
   "keywords": [
     "opencode",
@@ -38,8 +38,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "opencode-athena": "./dist/cli/index.js",
-    "athena": "./dist/cli/index.js"
+    "opencode-athena": "dist/cli/index.js",
+    "athena": "dist/cli/index.js"
   },
   "files": [
     "dist",