aw-ecc 1.4.21

package/commands/orchestrate.md

@@ -0,0 +1,240 @@
+---
+description: Sequential and tmux/worktree orchestration guidance for multi-agent workflows.
+---
+
+# Orchestrate Command
+
+Sequential agent workflow for complex tasks.
+
+## Usage
+
+`/orchestrate [workflow-type] [task-description]`
+
+## Workflow Types
+
+### feature
+Full feature implementation workflow:
+```
+planner -> tdd-guide -> code-reviewer -> security-reviewer
+```
+
+### bugfix
+Bug investigation and fix workflow:
+```
+planner -> tdd-guide -> code-reviewer
+```
+
+### refactor
+Safe refactoring workflow:
+```
+architect -> code-reviewer -> tdd-guide
+```
+
+### security
+Security-focused review:
+```
+security-reviewer -> code-reviewer -> architect
+```
+
+## Execution Pattern
+
+For each agent in the workflow:
+
+1. **Invoke agent** with context from previous agent
+2. **Collect output** as structured handoff document
+3. **Pass to next agent** in chain
+4. **Aggregate results** into final report
+
+## Handoff Document Format
+
+Between agents, create handoff document:
+
+```markdown
+## HANDOFF: [previous-agent] -> [next-agent]
+
+### Context
+[Summary of what was done]
+
+### Findings
+[Key discoveries or decisions]
+
+### Files Modified
+[List of files touched]
+
+### Open Questions
+[Unresolved items for next agent]
+
+### Recommendations
+[Suggested next steps]
+```
+
+## Example: Feature Workflow
+
+```
+/orchestrate feature "Add user authentication"
+```
+
+Executes:
+
+1. **Planner Agent**
+   - Analyzes requirements
+   - Creates implementation plan
+   - Identifies dependencies
+   - Output: `HANDOFF: planner -> tdd-guide`
+
+2. **TDD Guide Agent**
+   - Reads planner handoff
+   - Writes tests first
+   - Implements to pass tests
+   - Output: `HANDOFF: tdd-guide -> code-reviewer`
+
+3. **Code Reviewer Agent**
+   - Reviews implementation
+   - Checks for issues
+   - Suggests improvements
+   - Output: `HANDOFF: code-reviewer -> security-reviewer`
+
+4. **Security Reviewer Agent**
+   - Security audit
+   - Vulnerability check
+   - Final approval
+   - Output: Final Report
+
+## Final Report Format
+
+```
+ORCHESTRATION REPORT
+====================
+Workflow: feature
+Task: Add user authentication
+Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
+
+SUMMARY
+-------
+[One paragraph summary]
+
+AGENT OUTPUTS
+-------------
+Planner: [summary]
+TDD Guide: [summary]
+Code Reviewer: [summary]
+Security Reviewer: [summary]
+
+FILES CHANGED
+-------------
+[List all files modified]
+
+TEST RESULTS
+------------
+[Test pass/fail summary]
+
+SECURITY STATUS
+---------------
+[Security findings]
+
+RECOMMENDATION
+--------------
+[SHIP / NEEDS WORK / BLOCKED]
+```
+
+## Parallel Execution
+
+For independent checks, run agents in parallel:
+
+```markdown
+### Parallel Phase
+Run simultaneously:
+- code-reviewer (quality)
+- security-reviewer (security)
+- architect (design)
+
+### Merge Results
+Combine outputs into single report
+```
+
+For external tmux-pane workers with separate git worktrees, use `node scripts/orchestrate-worktrees.js plan.json --execute`. The built-in orchestration pattern stays in-process; the helper is for long-running or cross-harness sessions.
+
+When workers need to see dirty or untracked local files from the main checkout, add `seedPaths` to the plan file. ECC overlays only those selected paths into each worker worktree after `git worktree add`, which keeps the branch isolated while still exposing in-flight local scripts, plans, or docs.
+
+```json
+{
+  "sessionName": "workflow-e2e",
+  "seedPaths": [
+    "scripts/orchestrate-worktrees.js",
+    "scripts/lib/tmux-worktree-orchestrator.js",
+    ".claude/plan/workflow-e2e-test.json"
+  ],
+  "workers": [
+    { "name": "docs", "task": "Update orchestration docs." }
+  ]
+}
+```
+
+To export a control-plane snapshot for a live tmux/worktree session, run:
+
+```bash
+node scripts/orchestration-status.js .claude/plan/workflow-visual-proof.json
+```
+
+The snapshot includes session activity, tmux pane metadata, worker states, objectives, seeded overlays, and recent handoff summaries in JSON form.
+
+## Operator Command-Center Handoff
+
+When the workflow spans multiple sessions, worktrees, or tmux panes, append a control-plane block to the final handoff:
+
+```markdown
+CONTROL PLANE
+-------------
+Sessions:
+- active session ID or alias
+- branch + worktree path for each active worker
+- tmux pane or detached session name when applicable
+
+Diffs:
+- git status summary
+- git diff --stat for touched files
+- merge/conflict risk notes
+
+Approvals:
+- pending user approvals
+- blocked steps awaiting confirmation
+
+Telemetry:
+- last activity timestamp or idle signal
+- estimated token or cost drift
+- policy events raised by hooks or reviewers
+```
+
+This keeps planner, implementer, reviewer, and loop workers legible from the operator surface.
+
+## Arguments
+
+$ARGUMENTS:
+- `feature <description>` - Full feature workflow
+- `bugfix <description>` - Bug fix workflow
+- `refactor <description>` - Refactoring workflow
+- `security <description>` - Security review workflow
+- `custom <agents> <description>` - Custom agent sequence
+
+## Custom Workflow Example
+
+```
+/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"
+```
+
+## Tips
+
+1. **Start with planner** for complex features
+2. **Always include code-reviewer** before merge
+3. **Use security-reviewer** for auth/payment/PII
+4. **Keep handoffs concise** - focus on what next agent needs
+5. **Run verification** between agents if needed
+
+---
+
+## GHL Platform Integration
+
+Also activate the matching platform domain family resolved by `using-aw-skills`.
+- Testing/QA → `platform-sdet-*`
+
+For ALL activated agents: read frontmatter → load each skill from `skills:` array.

package/commands/plan.md

@@ -0,0 +1,130 @@
+---
+name: aw:plan
+description: Define the minimum correct planning artifacts for the request without drifting into execution.
+argument-hint: "<goal, request, or existing artifact>"
+status: active
+stage: plan
+internal_skill: aw-plan
+---
+
+# Plan
+
+Use `/aw:plan` to decide what needs to be planned and to produce only the planning artifacts required for the request.
+This command owns planning only.
+It should stay narrow by default and should not write implementation code.
+
+## Role
+
+Turn an idea, requirement, approved design, or technical request into the minimum correct planning artifacts for execution.
+
+## Modes
+
+| Mode | Use when | Primary outputs |
+|---|---|---|
+| `product` | problem, scope, or acceptance criteria are unclear | `prd.md`, `state.json` |
+| `design` | UX behavior or interface design must be defined | `design.md`, `designs/`, `state.json` |
+| `technical` | implementation approach or architecture must be defined | `spec.md`, `state.json` |
+| `tasks` | implementation work needs to be broken into steps | `tasks.md`, `state.json` |
+| `full` | multiple planning artifacts are missing | missing artifacts in order, plus `state.json` |
+
+## Required Inputs
+
+- the user request
+- repo context
+- relevant platform docs
+- relevant `.aw_rules`
+
+## Optional Inputs
+
+- existing `prd.md`
+- existing `design.md`
+- existing `designs/`
+- existing `spec.md`
+- existing `tasks.md`
+- tickets, bug reports, screenshots, API contracts, or Figma links
+
+## Outputs
+
+- `.aw_docs/features/<feature_slug>/state.json`
+- one or more of:
+  - `prd.md`
+  - `design.md`
+  - `designs/`
+  - `spec.md`
+  - `tasks.md`
+
+## Execution Rules
+
+1. Classify the request into one primary mode first.
+2. Operate in read-only planning mode until the artifacts are written.
+3. Default to single-scope planning.
+4. If the request is fuzzy, discovery-heavy, or too large for one spec, route internally through `aw-brainstorm` before technical planning.
+5. Use existing artifacts as inputs when they are already sufficient.
+6. Route approved technical direction through `aw-spec` before task planning.
+7. Route approved specs through `aw-tasks` when execution-ready tasks are missing or stale.
+8. Do not require a PRD for a technical request that is already well defined.
+9. When writing technical or task artifacts, make them concrete enough for build to proceed without re-planning file scope, validation, and task order.
+10. When writing `tasks.md`, always include an explicit `## Spec Brief` section and organize the work into explicit phases.
+
+## Planning Depth
+
+When `/aw:plan` writes `spec.md` or `tasks.md`, prefer:
+
+- an explicit `## Spec Brief` section at the top of `tasks.md`
+- exact file paths when they can be inferred safely
+- likely file scope when exact paths are not yet safe
+- dependency ordering and vertical slices instead of horizontal batches
+- phased task breakdown with explicit phase headings
+- concrete task goals
+- 2-5 minute checkbox steps for non-trivial work
+- exact commands with expected failure or pass signals
+- commit boundaries for meaningful slices
+- save-point commit expectation for meaningful slices
+- explicit `parallel_group`, `parallel_ready_when`, and `parallel_write_scope` details when work can fan out safely
+- `max_parallel_subagents: 3` by default for planned fan-out, unless another cap is explicitly justified
+- validation commands or evidence targets
+- checkpoints between major phases
+- dependency or ordering notes
+- bounded parallel candidates only when write scope is disjoint
+- no placeholders and a self-review pass before handoff
+
+## Hard Gates
+
+- do not write implementation code
+- do not run deploy steps
+- do not force unrelated artifacts
+- do not invent product or design work for a technical-only request
+
+## Must Not Do
+
+- must not jump directly into `/aw:build`
+- must not create random artifact names
+- must not silently broaden scope
+
+## Recommended Next Commands
+
+- `/aw:build`
+- `/aw:review` if the user wants the planning artifacts reviewed before implementation
+
+## Internal Routing
+
+This command may still use internal helpers where useful, but the public contract remains `/aw:plan`.
+
+- discovery-heavy ideation should use `aw-brainstorm`
+- technical contract authoring should use `aw-spec`
+- execution-recipe task writing should use `aw-tasks`
+- the primary stage skill remains `aw-plan`
+
+## Final Output Shape
+
+Always end with:
+
+- `Route`
+- `Mode`
+- `Created`
+- `Spec Brief`
+- `Phases`
+- `Summary`
+- `Execution Readiness`
+- `Missing`
+- `Next`

package/commands/pm2.md

@@ -0,0 +1,272 @@
+# PM2 Init
+
+Auto-analyze project and generate PM2 service commands.
+
+**Command**: `$ARGUMENTS`
+
+---
+
+## Workflow
+
+1. Check PM2 (install via `npm install -g pm2` if missing)
+2. Scan project to identify services (frontend/backend/database)
+3. Generate config files and individual command files
+
+---
+
+## Service Detection
+
+| Type | Detection | Default Port |
+|------|-----------|--------------|
+| Vite | vite.config.* | 5173 |
+| Next.js | next.config.* | 3000 |
+| Nuxt | nuxt.config.* | 3000 |
+| CRA | react-scripts in package.json | 3000 |
+| Express/Node | server/backend/api directory + package.json | 3000 |
+| FastAPI/Flask | requirements.txt / pyproject.toml | 8000 |
+| Go | go.mod / main.go | 8080 |
+
+**Port Detection Priority**: User specified > .env > config file > scripts args > default port
+
+---
+
+## Generated Files
+
+```
+project/
+├── ecosystem.config.cjs              # PM2 config
+├── {backend}/start.cjs               # Python wrapper (if applicable)
+└── .claude/
+    ├── commands/
+    │   ├── pm2-all.md                # Start all + monit
+    │   ├── pm2-all-stop.md           # Stop all
+    │   ├── pm2-all-restart.md        # Restart all
+    │   ├── pm2-{port}.md             # Start single + logs
+    │   ├── pm2-{port}-stop.md        # Stop single
+    │   ├── pm2-{port}-restart.md     # Restart single
+    │   ├── pm2-logs.md               # View all logs
+    │   └── pm2-status.md             # View status
+    └── scripts/
+        ├── pm2-logs-{port}.ps1       # Single service logs
+        └── pm2-monit.ps1             # PM2 monitor
+```
+
+---
+
+## Windows Configuration (IMPORTANT)
+
+### ecosystem.config.cjs
+
+**Must use `.cjs` extension**
+
+```javascript
+module.exports = {
+  apps: [
+    // Node.js (Vite/Next/Nuxt)
+    {
+      name: 'project-3000',
+      cwd: './packages/web',
+      script: 'node_modules/vite/bin/vite.js',
+      args: '--port 3000',
+      interpreter: 'C:/Program Files/nodejs/node.exe',
+      env: { NODE_ENV: 'development' }
+    },
+    // Python
+    {
+      name: 'project-8000',
+      cwd: './backend',
+      script: 'start.cjs',
+      interpreter: 'C:/Program Files/nodejs/node.exe',
+      env: { PYTHONUNBUFFERED: '1' }
+    }
+  ]
+}
+```
+
+**Framework script paths:**
+
+| Framework | script | args |
+|-----------|--------|------|
+| Vite | `node_modules/vite/bin/vite.js` | `--port {port}` |
+| Next.js | `node_modules/next/dist/bin/next` | `dev -p {port}` |
+| Nuxt | `node_modules/nuxt/bin/nuxt.mjs` | `dev --port {port}` |
+| Express | `src/index.js` or `server.js` | - |
+
+### Python Wrapper Script (start.cjs)
+
+```javascript
+const { spawn } = require('child_process');
+const proc = spawn('python', ['-m', 'uvicorn', 'app.main:app', '--host', '0.0.0.0', '--port', '8000', '--reload'], {
+  cwd: __dirname, stdio: 'inherit', windowsHide: true
+});
+proc.on('close', (code) => process.exit(code));
+```
+
+---
+
+## Command File Templates (Minimal Content)
+
+### pm2-all.md (Start all + monit)
+````markdown
+Start all services and open PM2 monitor.
+```bash
+cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 monit"
+```
+````
+
+### pm2-all-stop.md
+````markdown
+Stop all services.
+```bash
+cd "{PROJECT_ROOT}" && pm2 stop all
+```
+````
+
+### pm2-all-restart.md
+````markdown
+Restart all services.
+```bash
+cd "{PROJECT_ROOT}" && pm2 restart all
+```
+````
+
+### pm2-{port}.md (Start single + logs)
+````markdown
+Start {name} ({port}) and open logs.
+```bash
+cd "{PROJECT_ROOT}" && pm2 start ecosystem.config.cjs --only {name} && start wt.exe -d "{PROJECT_ROOT}" pwsh -NoExit -c "pm2 logs {name}"
+```
+````
+
+### pm2-{port}-stop.md
+````markdown
+Stop {name} ({port}).
+```bash
+cd "{PROJECT_ROOT}" && pm2 stop {name}
+```
+````
+
+### pm2-{port}-restart.md
+````markdown
+Restart {name} ({port}).
+```bash
+cd "{PROJECT_ROOT}" && pm2 restart {name}
+```
+````
+
+### pm2-logs.md
+````markdown
+View all PM2 logs.
+```bash
+cd "{PROJECT_ROOT}" && pm2 logs
+```
+````
+
+### pm2-status.md
+````markdown
+View PM2 status.
+```bash
+cd "{PROJECT_ROOT}" && pm2 status
+```
+````
+
+### PowerShell Scripts (pm2-logs-{port}.ps1)
+```powershell
+Set-Location "{PROJECT_ROOT}"
+pm2 logs {name}
+```
+
+### PowerShell Scripts (pm2-monit.ps1)
+```powershell
+Set-Location "{PROJECT_ROOT}"
+pm2 monit
+```
+
+---
+
+## Key Rules
+
+1. **Config file**: `ecosystem.config.cjs` (not .js)
+2. **Node.js**: Specify bin path directly + interpreter
+3. **Python**: Node.js wrapper script + `windowsHide: true`
+4. **Open new window**: `start wt.exe -d "{path}" pwsh -NoExit -c "command"`
+5. **Minimal content**: Each command file has only 1-2 lines description + bash block
+6. **Direct execution**: No AI parsing needed, just run the bash command
+
+---
+
+## Execute
+
+Based on `$ARGUMENTS`, execute init:
+
+1. Scan project for services
+2. Generate `ecosystem.config.cjs`
+3. Generate `{backend}/start.cjs` for Python services (if applicable)
+4. Generate command files in `.claude/commands/`
+5. Generate script files in `.claude/scripts/`
+6. **Update project CLAUDE.md** with PM2 info (see below)
+7. **Display completion summary** with terminal commands
+
+---
+
+## Post-Init: Update CLAUDE.md
+
+After generating files, append PM2 section to project's `CLAUDE.md` (create if not exists):
+
+````markdown
+## PM2 Services
+
+| Port | Name | Type |
+|------|------|------|
+| {port} | {name} | {type} |
+
+**Terminal Commands:**
+```bash
+pm2 start ecosystem.config.cjs   # First time
+pm2 start all                    # After first time
+pm2 stop all / pm2 restart all
+pm2 start {name} / pm2 stop {name}
+pm2 logs / pm2 status / pm2 monit
+pm2 save                         # Save process list
+pm2 resurrect                    # Restore saved list
+```
+````
+
+**Rules for CLAUDE.md update:**
+- If PM2 section exists, replace it
+- If not exists, append to end
+- Keep content minimal and essential
+
+---
+
+## Post-Init: Display Summary
+
+After all files generated, output:
+
+```
+## PM2 Init Complete
+
+**Services:**
+
+| Port | Name | Type |
+|------|------|------|
+| {port} | {name} | {type} |
+
+**Claude Commands:** /pm2-all, /pm2-all-stop, /pm2-{port}, /pm2-{port}-stop, /pm2-logs, /pm2-status
+
+**Terminal Commands:**
+## First time (with config file)
+pm2 start ecosystem.config.cjs && pm2 save
+
+## After first time (simplified)
+pm2 start all          # Start all
+pm2 stop all           # Stop all
+pm2 restart all        # Restart all
+pm2 start {name}       # Start single
+pm2 stop {name}        # Stop single
+pm2 logs               # View logs
+pm2 monit              # Monitor panel
+pm2 resurrect          # Restore saved processes
+
+**Tip:** Run `pm2 save` after first start to enable simplified commands.
+```

package/commands/projects.md

@@ -0,0 +1,39 @@
+---
+name: projects
+description: List known projects and their instinct statistics
+command: true
+---
+
+# Projects Command
+
+List project registry entries and per-project instinct/observation counts for continuous-learning-v2.
+
+## Implementation
+
+Run the instinct CLI using the plugin root path:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/skills/continuous-learning-v2/scripts/instinct-cli.py" projects
+```
+
+Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py projects
+```
+
+## Usage
+
+```bash
+/projects
+```
+
+## What to Do
+
+1. Read `~/.claude/homunculus/projects.json`
+2. For each project, display:
+   - Project name, id, root, remote
+   - Personal and inherited instinct counts
+   - Observation event count
+   - Last seen timestamp
+3. Also display global instinct totals