agentsys 5.0.0

package/adapters/opencode/commands/ship-error-handling.md

@@ -0,0 +1,248 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+agent: general
+---
+
+> **OpenCode Note**: Invoke agents using `@agent-name` syntax.
+> Available agents: task-discoverer, exploration-agent, planning-agent,
+> implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent
+> Example: `@exploration-agent analyze the codebase`
+
+
+# Error Handling & Recovery - Reference
+
+This file contains error handling procedures for `/ship`.
+
+**Parent document**: `ship.md`
+
+## GitHub CLI Not Available
+
+```markdown
+ERROR: GitHub CLI (gh) not found
+
+Install: https://cli.github.com
+
+Or use package manager:
+  macOS: brew install gh
+  Windows: winget install GitHub.cli
+  Linux: See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+
+Then authenticate:
+  gh auth login
+```
+
+## CI Failure
+
+```markdown
+[ERROR] CI checks failed for PR #${PR_NUMBER}
+
+View details:
+  ${CI_URL}
+
+Fix the failing tests/checks and push again.
+The /ship command will resume from Phase 4 (CI monitoring).
+
+To retry:
+  git push
+  /ship
+```
+
+### CI Fix with ci-fixer Agent
+
+When CI fails, use the ci-fixer agent:
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Merge Conflicts
+
+```markdown
+[ERROR] Cannot merge PR #${PR_NUMBER}: conflicts with ${MAIN_BRANCH}
+
+Resolve conflicts:
+  git fetch origin
+  git merge origin/${MAIN_BRANCH}
+  # Resolve conflicts in your editor
+  git add .
+  git commit
+  git push
+
+Then retry:
+  /ship
+```
+
+## Deployment Failure
+
+```markdown
+[ERROR] Deployment failed
+
+${WORKFLOW === 'dev-prod' ? 'Development' : 'Production'} deployment did not succeed.
+
+Check deployment logs:
+  ${DEPLOYMENT === 'railway' ? 'railway logs' : ''}
+  ${DEPLOYMENT === 'vercel' ? 'vercel logs' : ''}
+  ${DEPLOYMENT === 'netlify' ? 'netlify logs' : ''}
+
+Once fixed, deployment will retry automatically.
+```
+
+## Production Validation Failure with Rollback
+
+```markdown
+[ERROR] Production validation failed
+
+ROLLBACK INITIATED
+
+Production has been rolled back to previous version.
+Previous deployment: ${PREVIOUS_SHA}
+
+Issues detected:
+  ${VALIDATION_ISSUES}
+
+Fix the issues and try shipping again:
+  /ship
+```
+
+## Push Failure
+
+```markdown
+[ERROR] Push to remote failed
+
+Possible causes:
+1. Authentication issue: gh auth status
+2. Remote branch protected: check branch protection rules
+3. Out of date: git pull --rebase origin ${CURRENT_BRANCH}
+
+Resolve and retry:
+  /ship
+```
+
+## PR Creation Failure
+
+```markdown
+[ERROR] Failed to create PR
+
+Possible causes:
+1. Already exists: gh pr list --head ${CURRENT_BRANCH}
+2. No commits: git log ${MAIN_BRANCH}..HEAD
+3. Same branch: ensure not on ${MAIN_BRANCH}
+
+Check existing PRs:
+  gh pr list --state all --head ${CURRENT_BRANCH}
+```
+
+## Max Review Iterations Reached
+
+```markdown
+[ERROR] Max iterations (${MAX_ITERATIONS}) reached
+
+Unable to resolve all review comments automatically.
+Manual intervention required.
+
+Remaining unresolved threads: ${UNRESOLVED_COUNT}
+
+View PR: ${PR_URL}
+
+Options:
+1. Manually address remaining comments
+2. Request reviewer to close non-blocking items
+3. Continue with /ship after resolving
+```
+
+## Worktree Cleanup Failure
+
+```markdown
+[WARN] Failed to clean up worktree
+
+Worktree at: ${WORKTREE_PATH}
+
+Manual cleanup:
+  git worktree remove ${WORKTREE_PATH} --force
+  git worktree prune
+```
+
+## Force Push Safety
+
+When rollback requires force push:
+
+```bash
+# ALWAYS use --force-with-lease instead of --force
+# This prevents overwriting unexpected remote changes
+
+if ! git push --force-with-lease origin $PROD_BRANCH; then
+  echo "[ERROR] Force push failed - remote has unexpected changes"
+  echo "Someone else may have pushed to production"
+  echo "Manual investigation required"
+  exit 1
+fi
+```
+
+## Recovery Procedures
+
+### Resume After CI Fix
+
+```bash
+# After fixing CI locally
+git add .
+git commit -m "fix: address CI failures"
+git push
+
+# Resume shipping
+/ship
+```
+
+### Resume After Conflict Resolution
+
+```bash
+# After resolving merge conflicts
+git add .
+git commit
+git push
+
+# Resume shipping
+/ship
+```
+
+### Resume After Manual Review Resolution
+
+```bash
+# After manually addressing review comments
+git add .
+git commit -m "fix: address review feedback"
+git push
+
+# Resume shipping
+/ship
+```
+
+### Cancel and Cleanup
+
+```bash
+# If you need to abandon the PR
+gh pr close $PR_NUMBER --delete-branch
+
+# Clean up local
+git checkout $MAIN_BRANCH
+git branch -D $CURRENT_BRANCH
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success - PR merged |
+| 1 | General failure |
+| 2 | CI failure (retryable) |
+| 3 | Review timeout (manual intervention) |
+| 4 | Deployment failure |
+| 5 | Rollback triggered |
+
+## Logging for Debugging
+
+Enable verbose logging:
+
+```bash
+export SHIP_DEBUG=1
+/ship
+```
+
+This will output detailed information about each phase for troubleshooting.

package/adapters/opencode/commands/ship.md

@@ -0,0 +1,371 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+description: Complete PR workflow from commit to production with validation
+agent: general
+---
+
+> **OpenCode Note**: Invoke agents using `@agent-name` syntax.
+> Available agents: task-discoverer, exploration-agent, planning-agent,
+> implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent
+> Example: `@exploration-agent analyze the codebase`
+
+
+# /ship - Complete PR Workflow
+
+End-to-end workflow: commit - PR - CI - review - merge - deploy - validate - production.
+
+Auto-adapts to your project's CI platform, deployment platform, and branch strategy.
+
+---
+
+<mandatory-steps>
+## Mandatory Steps - No Shortcuts
+
+Phase 4 (CI & Review Monitor Loop) is mandatory even when called from /next-task.
+
+| Step | Requirement | Why It Matters |
+|------|-------------|----------------|
+| 3-minute initial wait | Must wait after PR creation | Auto-reviewers need time to analyze |
+| Monitor loop iterations | Must run the full loop | Catches issues humans miss |
+| Address all comments | Zero unresolved threads | Quality gate, blocks merge otherwise |
+
+### Forbidden Actions
+- Checking CI once and proceeding to merge
+- Skipping the 3-minute initial wait for auto-reviewers
+- Ignoring "minor" or "nit" comments
+- Merging with unresolved comment threads
+- Rationalizing "no comments yet means ready to merge"
+
+### Required Verification Output
+
+Before proceeding to merge, output:
+```
+[VERIFIED] Phase 4: wait=180s, iterations=N, unresolved=0
+```
+</mandatory-steps>
+
+---
+
+## Quick Reference
+
+| Phase | Description | Details |
+|-------|-------------|---------|
+| 1-3 | Pre-flight, Commit, Create PR | This file |
+| 4 | CI & Review Monitor Loop | See `ship-ci-review-loop.md` |
+| 5 | Subagent Review (standalone) | This file |
+| 6 | Merge PR | This file |
+| 7-10 | Deploy & Validate | See `ship-deployment.md` |
+| 11-12 | Cleanup & Report | This file |
+| Errors | Error handling & rollback | See `ship-error-handling.md` |
+
+## Integration with /next-task
+
+When called from `/next-task` workflow (via `--state-file`):
+- **SKIPS Phase 5** internal review agents (already done by Phase 9 review loop)
+- **SKIPS deslop/docs** (already done by deslop-agent, sync-docs-agent)
+- **Trusts** that all quality gates passed
+
+**CRITICAL: Phase 4 ALWAYS runs** - even from /next-task. External auto-reviewers (Gemini, Copilot, CodeRabbit) comment AFTER PR creation and must be addressed.
+
+When called standalone, runs full workflow including review.
+
+## Arguments
+
+Parse from $ARGUMENTS:
+- **--strategy**: Merge strategy: `squash` (default) | `merge` | `rebase`
+- **--skip-tests**: Skip test validation (dangerous)
+- **--dry-run**: Show what would happen without executing
+- **--state-file**: Path to workflow state file (for /next-task integration)
+
+## State Integration
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Phase 1: Pre-flight Checks
+
+*(Bash command with Node.js require - adapt for OpenCode)*
+
+### Verify Git Status
+
+```bash
+# Check for uncommitted changes
+if [ -n "$(git status --porcelain)" ]; then
+  NEEDS_COMMIT="true"
+else
+  NEEDS_COMMIT="false"
+fi
+
+# Must be on feature branch
+CURRENT_BRANCH=$(git branch --show-current)
+if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ]; then
+  echo "ERROR: Cannot ship from $MAIN_BRANCH, must be on feature branch"
+  exit 1
+fi
+```
+
+### Dry Run Mode
+
+If `--dry-run` provided, show plan and exit:
+```markdown
+## Dry Run: What Would Happen
+**Branch**: ${CURRENT_BRANCH} → **Target**: ${MAIN_BRANCH}
+**Workflow**: ${WORKFLOW} | **CI**: ${CI_PLATFORM} | **Deploy**: ${DEPLOYMENT}
+```
+
+## Phase 2: Commit Current Work
+
+Only if `NEEDS_COMMIT=true`:
+
+```bash
+# Stage relevant files (exclude secrets)
+git status --porcelain | awk '{print $2}' | grep -v '\.env' | xargs git add
+
+# Generate semantic commit message
+# Format: <type>(<scope>): <subject>
+# Types: feat, fix, docs, refactor, test, chore
+
+git commit -m "$(cat <<'EOF'
+${COMMIT_MESSAGE}
+EOF
+)"
+
+COMMIT_SHA=$(git rev-parse HEAD)
+echo "[OK] Committed: $COMMIT_SHA"
+```
+
+## Phase 3: Create Pull Request
+
+```bash
+# Push to remote
+git push -u origin $CURRENT_BRANCH
+
+# Create PR
+PR_URL=$(gh pr create \
+  --base "$MAIN_BRANCH" \
+  --title "$PR_TITLE" \
+  --body "$(cat <<'EOF'
+## Summary
+- Bullet points of changes
+
+## Test Plan
+- How to test
+
+## Related Issues
+Closes #X
+EOF
+)")
+
+PR_NUMBER=$(echo $PR_URL | grep -oP '/pull/\K\d+')
+echo "[OK] Created PR #$PR_NUMBER: $PR_URL"
+```
+
+<phase-4>
+## Phase 4: CI & Review Monitor Loop
+
+**Blocking gate** - This phase is mandatory. Cannot proceed to merge without completing.
+
+See `ship-ci-review-loop.md` for full implementation details.
+
+### Summary
+
+The monitor loop must:
+1. Wait for CI to pass
+2. Wait 3 minutes for auto-reviewers (mandatory on first iteration)
+3. Address all comments (zero unresolved threads)
+4. Iterate until clean
+
+**Every comment must be addressed:**
+- Critical/High issues: Fix immediately
+- Medium/Minor issues: Fix (shows quality)
+- Questions: Answer with explanation
+- False positives: Reply explaining why, then resolve
+
+Do not ignore comments. Do not leave comments unresolved.
+Do not skip the 3-minute wait. Do not check CI once and merge.
+
+### Loop Structure
+
+```bash
+MAX_ITERATIONS=10
+INITIAL_WAIT=180  # 3 minutes - do not reduce or skip
+
+iteration=0
+while [ $iteration -lt $MAX_ITERATIONS ]; do
+  iteration=$((iteration + 1))
+  echo "[CI Monitor] Iteration $iteration"
+
+  # 1. Wait for CI to complete
+  wait_for_ci || { fix_ci_failures; continue; }
+
+  # 2. First iteration must wait for auto-reviews
+  if [ $iteration -eq 1 ]; then
+    echo "Waiting ${INITIAL_WAIT}s for auto-reviewers..."
+    sleep $INITIAL_WAIT
+    echo "[DONE] Initial wait complete"
+  fi
+
+  # 3. Check feedback
+  FEEDBACK=$(check_pr_feedback $PR_NUMBER)
+  UNRESOLVED=$(echo "$FEEDBACK" | jq -r '.unresolvedThreads')
+
+  echo "Unresolved threads: $UNRESOLVED"
+
+  # 4. Exit only if zero unresolved
+  if [ "$UNRESOLVED" -eq 0 ]; then
+    echo "[OK] All comments resolved - ready to merge"
+    break
+  fi
+
+  # 5. Address all feedback (see ship-ci-review-loop.md)
+  address_all_feedback $PR_NUMBER
+
+  # 6. Commit and push fixes
+  commit_and_push_fixes "fix: address review feedback (iteration $iteration)"
+
+  # 7. Wait before next iteration
+  sleep 30
+done
+
+# Verification output - mandatory
+echo "[VERIFIED] Phase 4: wait=180s, iterations=$iteration, unresolved=0"
+```
+
+### Forbidden Actions in Phase 4
+- `sleep 0` or removing the initial wait
+- Checking CI once without running the loop
+- Breaking out of loop with unresolved comments
+- Skipping to Phase 6 (merge) without verification output
+</phase-4>
+
+## Phase 5: Review Loop (Standalone Only)
+
+**Skip if called from /next-task** (review already done).
+
+*(JavaScript reference - not executable in OpenCode)*
+
+When running standalone, launch core review passes in parallel (error handling is part of code quality):
+
+*(JavaScript reference - not executable in OpenCode)*
+
+Iterate until no open (non-false-positive) issues remain (max 3 iterations if running standalone).
+
+<phase-6>
+## Phase 6: Merge PR
+
+Pre-merge checks (do not skip):
+
+*(Bash command with Node.js require - adapt for OpenCode)*
+</phase-6>
+
+## Phases 7-10: Deploy & Validate
+
+**Skip if `WORKFLOW="single-branch"`**
+
+See `ship-deployment.md` for platform-specific details:
+- Phase 7: Deploy to Development (Railway, Vercel, Netlify)
+- Phase 8: Validate Development (health checks, smoke tests)
+- Phase 9: Deploy to Production (merge to prod branch)
+- Phase 10: Validate Production (with auto-rollback on failure)
+
+## Phase 11: Cleanup
+
+```bash
+# Clean up worktrees
+git worktree list --porcelain | grep "worktree" | grep -v "$(git rev-parse --show-toplevel)" | while read -r wt; do
+  WORKTREE_PATH=$(echo $wt | awk '{print $2}')
+  git worktree remove $WORKTREE_PATH --force 2>/dev/null || true
+done
+```
+
+### Close GitHub Issue (if applicable)
+
+If the task came from a GitHub issue, close it with a completion comment:
+
+```bash
+if [ -n "$TASK_ID" ] && [ "$TASK_SOURCE" = "github" ]; then
+  # Post completion comment
+  gh issue comment "$TASK_ID" --body "$(cat <<'EOF'
+[DONE] **Task Completed Successfully**
+
+**PR**: #${PR_NUMBER}
+**Status**: Merged to ${MAIN_BRANCH}
+**Commit**: ${MERGE_SHA}
+
+### Summary
+- Implementation completed as planned
+- All review comments addressed
+- CI checks passed
+- Merged successfully
+
+---
+_This issue was automatically processed by AgentSys /next-task workflow._
+_Closing issue as the work has been completed and merged._
+EOF
+)"
+
+  # Close the issue
+  gh issue close "$TASK_ID" --reason completed
+
+  echo "[OK] Closed issue #$TASK_ID with completion comment"
+fi
+```
+
+### Remove Task from Registry
+
+*(JavaScript reference - not executable in OpenCode)*
+
+### Local Branch Cleanup
+
+```bash
+git checkout $MAIN_BRANCH
+# Feature branch already deleted by --delete-branch
+git branch -D $CURRENT_BRANCH 2>/dev/null || true
+```
+
+## Phase 12: Completion Report
+
+```markdown
+# Deployment Complete
+
+## Pull Request
+**Number**: #${PR_NUMBER} | **Status**: Merged to ${MAIN_BRANCH}
+
+## Review Results
+- Code Quality: [OK] | Error Handling: [OK] | Test Coverage: [OK] | CI: [OK]
+
+## Deployments
+${WORKFLOW === 'dev-prod' ?
+  `Development: ${DEV_URL} [OK] | Production: ${PROD_URL} [OK]` :
+  `Production: Deployed to ${MAIN_BRANCH}`}
+
+[OK] Successfully shipped!
+```
+
+### Workflow Hook Response
+
+After displaying the completion report, output JSON for the SubagentStop hook:
+
+```json
+{"ok": true, "nextPhase": "completed", "status": "shipped"}
+```
+
+This allows the `/next-task` workflow to detect that `/ship` completed successfully.
+
+## Error Handling
+
+See `ship-error-handling.md` for detailed error handling:
+- GitHub CLI not available
+- CI failures
+- Merge conflicts
+- Deployment failures
+- Production validation failures with rollback
+
+## Important Notes
+
+- Requires GitHub CLI (gh) for PR workflow
+- Auto-adapts to single-branch or multi-branch workflow
+- Platform-specific CI and deployment monitoring
+- Automatic rollback on production failures
+- Respects project conventions (commit style, PR format)
+
+Begin Phase 1 now.

package/adapters/opencode/commands/sync-docs.md

@@ -0,0 +1,108 @@
+<!-- AUTO-GENERATED by scripts/gen-adapters.js - DO NOT EDIT -->
+---
+description: Use when user asks to "update docs", "sync documentation", "fix outdated docs", "update changelog", "docs are stale", or after completing code changes that might affect documentation.
+agent: general
+---
+
+> **OpenCode Note**: Invoke agents using `@agent-name` syntax.
+> Available agents: task-discoverer, exploration-agent, planning-agent,
+> implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent
+> Example: `@exploration-agent analyze the codebase`
+
+
+# /sync-docs - Documentation Sync
+
+Sync documentation with actual code state. Finds docs that reference changed files, updates CHANGELOG, and flags outdated examples.
+
+## Architecture
+
+```
+/sync-docs command (you are here)
+    |
+    v
+sync-docs-agent (sonnet)
+    |-- Invoke sync-docs skill
+    |-- Return structured results
+    |
+    v
+Command processes results
+    |-- If apply mode + fixes: spawn simple-fixer
+    |-- Present final results
+```
+
+## Constraints
+
+1. **Preserve existing content** - Update references, don't rewrite sections
+2. **Minimal changes** - Only fix what's actually outdated
+3. **Evidence-based** - Every change linked to a specific code change
+4. **Safe defaults** - Report mode by default
+
+## Arguments
+
+Parse from $ARGUMENTS:
+
+- **Mode**: `report` (default) or `apply`
+- **Scope**:
+  - `--scope=recent` (default): Files changed since last commit to main
+  - `--scope=all`: Scan all docs against all code
+  - `--scope=before-pr`: Files in current branch (for /next-task integration)
+  - `path`: Specific file or directory
+
+## Execution
+
+### Step 1: Parse Arguments
+
+*(JavaScript reference - not executable in OpenCode)*
+
+### Step 2: Spawn sync-docs-agent
+
+*(JavaScript reference - not executable in OpenCode)*
+
+### Step 3: Process Results
+
+Parse the structured JSON from between `=== SYNC_DOCS_RESULT ===` markers:
+
+*(JavaScript reference - not executable in OpenCode)*
+
+### Step 4: Apply Fixes (if apply mode)
+
+If mode is `apply` and fixes array is non-empty:
+
+*(JavaScript reference - not executable in OpenCode)*
+
+### Step 5: Present Results
+
+*(JavaScript reference - not executable in OpenCode)*
+
+## Examples
+
+```bash
+# Check what docs might need updates (safe, no changes)
+/sync-docs
+
+# Check docs related to specific path
+/sync-docs report src/auth/
+
+# Apply safe fixes
+/sync-docs apply
+
+# Full codebase scan
+/sync-docs report --scope=all
+
+# For PR preparation
+/sync-docs apply --scope=before-pr
+```
+
+## Integration
+
+This command is also used by `/next-task` Phase 11:
+
+- Invoke `@sync-docs-agent` agent
+
+
+## Error Handling
+
+- **No git**: Exit with "Git required for change detection"
+- **No changed files**: "No changes detected. Use --scope=all to scan entire codebase"
+- **No docs found**: "No documentation files found"
+- **Agent failure**: Report error, suggest manual review