compact-agent 1.10.0 → 1.11.0

package/resources/ecc/commands/project-init.md

@@ -0,0 +1,86 @@
+---
+description: Detect a project's stack and produce a dry-run ECC onboarding plan using the repository's install manifests and stack mappings.
+---
+
+# /project-init
+
+Create a safe, reviewable ECC onboarding plan for the current project. This command should start in dry-run mode and only write files after explicit user approval.
+
+## Usage
+
+```text
+/project-init
+/project-init --dry-run
+/project-init --target claude
+/project-init --target cursor
+/project-init --skills continuous-learning-v2,security-review
+/project-init --config ecc-install.json
+```
+
+## Safety Rules
+
+1. Default to dry-run. Do not modify `CLAUDE.md`, settings files, rules, skills, or install state until the user approves the concrete plan.
+2. Preserve existing project guidance. If `CLAUDE.md`, `.claude/settings.local.json`, `.cursor/`, `.codex/`, `.gemini/`, `.opencode/`, `.codebuddy/`, `.joycode/`, or `.qwen/` already exists, inspect it and propose a merge/append plan instead of overwriting.
+3. Use ECC's installer and manifest tooling. Do not hand-copy files or clone arbitrary remotes as an install shortcut.
+4. Keep permissions narrow. Any generated settings should match detected build/test/lint tools and avoid broad shell access.
+5. Report exactly what would change before applying anything.
+
+## Detection Inputs
+
+Read the current project root and detect stack signals from:
+
+- package manager files: `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`
+- language manifests: `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `build.gradle.kts`
+- framework files: `next.config.*`, `vite.config.*`, `tailwind.config.*`, `Dockerfile`, `docker-compose.yml`
+- ECC config: `ecc-install.json`
+- optional stack map: `config/project-stack-mappings.json` in the ECC repo
+
+When the ECC checkout is available, use `config/project-stack-mappings.json` as the stack-to-rules/skills reference. If the file is unavailable, fall back to the installed ECC manifests and explicit user choices.
+
+## Planning Flow
+
+1. Identify the target harness. Default to `claude` unless the user asks for `cursor`, `codex`, `gemini`, `opencode`, `codebuddy`, `joycode`, or `qwen`.
+2. Detect stacks from project files and show the evidence for each match.
+3. Resolve the smallest useful ECC plan:
+   - project has an `ecc-install.json`: `node scripts/install-plan.js --config ecc-install.json --json`
+   - user named a profile: `node scripts/install-plan.js --profile <profile> --target <target> --json`
+   - user named skills: `node scripts/install-plan.js --skills <skill-ids> --target <target> --json`
+   - only language stacks are detected: use the legacy language install dry-run with those language names
+4. Run a dry-run apply command before writing:
+
+```bash
+node scripts/install-apply.js --target <target> --dry-run --json <language-or-profile-args>
+```
+
+5. Summarize detected stacks, selected modules/components/skills, target paths, skipped unsupported modules, and files that would be changed.
+6. Ask for approval before applying the non-dry-run command.
+
+## Output Contract
+
+Return:
+
+1. detected stack evidence
+2. proposed target harness
+3. exact dry-run command used
+4. exact apply command to run after approval
+5. files/directories that would be created or changed
+6. warnings about existing files, broad permissions, missing scripts, or unsupported targets
+
+## CLAUDE.md Guidance
+
+If the user wants a `CLAUDE.md` starter, generate it separately from the installer plan and keep it minimal:
+
+- build command, if detected
+- test command, if detected
+- lint/typecheck command, if detected
+- dev server command, if detected
+- repo-specific notes from existing package scripts or manifests
+
+Never replace an existing `CLAUDE.md` without showing a diff and receiving approval.
+
+## Related
+
+- `config/project-stack-mappings.json` for stack-to-surface hints
+- `scripts/install-plan.js` for deterministic plan resolution
+- `scripts/install-apply.js` for dry-run and apply operations
+- `/ecc-guide` for interactive feature discovery before installing

package/resources/ecc/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

package/resources/ecc/commands/promote.md

@@ -0,0 +1,41 @@
+---
+name: promote
+description: Promote project-scoped instincts to global scope
+command: true
+---
+
+# Promote Command
+
+Promote instincts from project scope to global scope in 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" promote [instinct-id] [--force] [--dry-run]
+```
+
+Or if `CLAUDE_PLUGIN_ROOT` is not set (manual installation):
+
+```bash
+python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py promote [instinct-id] [--force] [--dry-run]
+```
+
+## Usage
+
+```bash
+/promote                      # Auto-detect promotion candidates
+/promote --dry-run            # Preview auto-promotion candidates
+/promote --force              # Promote all qualified candidates without prompt
+/promote grep-before-edit     # Promote one specific instinct from current project
+```
+
+## What to Do
+
+1. Detect current project
+2. If `instinct-id` is provided, promote only that instinct (if present in current project)
+3. Otherwise, find cross-project candidates that:
+   - Appear in at least 2 projects
+   - Meet confidence threshold
+4. Write promoted instincts to `~/.claude/homunculus/instincts/personal/` with `scope: global`

package/resources/ecc/commands/prp-commit.md

@@ -0,0 +1,112 @@
+---
+description: "Quick commit with natural language file targeting — describe what to commit in plain English"
+argument-hint: "[target description] (blank = all changes)"
+---
+
+# Smart Commit
+
+> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
+
+**Input**: $ARGUMENTS
+
+---
+
+## Phase 1 — ASSESS
+
+```bash
+git status --short
+```
+
+If output is empty → stop: "Nothing to commit."
+
+Show the user a summary of what's changed (added, modified, deleted, untracked).
+
+---
+
+## Phase 2 — INTERPRET & STAGE
+
+Interpret `$ARGUMENTS` to determine what to stage:
+
+| Input | Interpretation | Git Command |
+|---|---|---|
+| *(blank / empty)* | Stage everything | `git add -A` |
+| `staged` | Use whatever is already staged | *(no git add)* |
+| `*.ts` or `*.py` etc. | Stage matching glob | `git add '*.ts'` |
+| `except tests` | Stage all, then unstage tests | `git add -A && git reset -- '**/*.test.*' '**/*.spec.*' '**/test_*' 2>/dev/null \|\| true` |
+| `only new files` | Stage untracked files only | `git ls-files --others --exclude-standard \| grep . && git ls-files --others --exclude-standard \| xargs git add` |
+| `the auth changes` | Interpret from status/diff — find auth-related files | `git add <matched files>` |
+| Specific filenames | Stage those files | `git add <files>` |
+
+For natural language inputs (like "the auth changes"), cross-reference the `git status` output and `git diff` to identify relevant files. Show the user which files you're staging and why.
+
+```bash
+git add <determined files>
+```
+
+After staging, verify:
+```bash
+git diff --cached --stat
+```
+
+If nothing staged, stop: "No files matched your description."
+
+---
+
+## Phase 3 — COMMIT
+
+Craft a single-line commit message in imperative mood:
+
+```
+{type}: {description}
+```
+
+Types:
+- `feat` — New feature or capability
+- `fix` — Bug fix
+- `refactor` — Code restructuring without behavior change
+- `docs` — Documentation changes
+- `test` — Adding or updating tests
+- `chore` — Build, config, dependencies
+- `perf` — Performance improvement
+- `ci` — CI/CD changes
+
+Rules:
+- Imperative mood ("add feature" not "added feature")
+- Lowercase after the type prefix
+- No period at the end
+- Under 72 characters
+- Describe WHAT changed, not HOW
+
+```bash
+git commit -m "{type}: {description}"
+```
+
+---
+
+## Phase 4 — OUTPUT
+
+Report to user:
+
+```
+Committed: {hash_short}
+Message:   {type}: {description}
+Files:     {count} file(s) changed
+
+Next steps:
+  - git push           → push to remote
+  - /prp-pr            → create a pull request
+  - /code-review       → review before pushing
+```
+
+---
+
+## Examples
+
+| You say | What happens |
+|---|---|
+| `/prp-commit` | Stages all, auto-generates message |
+| `/prp-commit staged` | Commits only what's already staged |
+| `/prp-commit *.ts` | Stages all TypeScript files, commits |
+| `/prp-commit except tests` | Stages everything except test files |
+| `/prp-commit the database migration` | Finds DB migration files from status, stages them |
+| `/prp-commit only new files` | Stages untracked files only |

package/resources/ecc/commands/prp-implement.md

@@ -0,0 +1,385 @@
+---
+description: Execute an implementation plan with rigorous validation loops
+argument-hint: <path/to/plan.md>
+---
+
+> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
+
+# PRP Implement
+
+Execute a plan file step-by-step with continuous validation. Every change is verified immediately — never accumulate broken state.
+
+**Core Philosophy**: Validation loops catch mistakes early. Run checks after every change. Fix issues immediately.
+
+**Golden Rule**: If a validation fails, fix it before moving on. Never accumulate broken state.
+
+---
+
+## Phase 0 — DETECT
+
+### Package Manager Detection
+
+| File Exists | Package Manager | Runner |
+|---|---|---|
+| `bun.lockb` | bun | `bun run` |
+| `pnpm-lock.yaml` | pnpm | `pnpm run` |
+| `yarn.lock` | yarn | `yarn` |
+| `package-lock.json` | npm | `npm run` |
+| `pyproject.toml` or `requirements.txt` | uv / pip | `uv run` or `python -m` |
+| `Cargo.toml` | cargo | `cargo` |
+| `go.mod` | go | `go` |
+
+### Validation Scripts
+
+Check `package.json` (or equivalent) for available scripts:
+
+```bash
+# For Node.js projects
+cat package.json | grep -A 20 '"scripts"'
+```
+
+Note available commands for: type-check, lint, test, build.
+
+---
+
+## Phase 1 — LOAD
+
+Read the plan file:
+
+```bash
+cat "$ARGUMENTS"
+```
+
+Extract these sections from the plan:
+- **Summary** — What is being built
+- **Patterns to Mirror** — Code conventions to follow
+- **Files to Change** — What to create or modify
+- **Step-by-Step Tasks** — Implementation sequence
+- **Validation Commands** — How to verify correctness
+- **Acceptance Criteria** — Definition of done
+
+If the file doesn't exist or isn't a valid plan:
+```
+Error: Plan file not found or invalid.
+Run /prp-plan <feature-description> to create a plan first.
+```
+
+**CHECKPOINT**: Plan loaded. All sections identified. Tasks extracted.
+
+---
+
+## Phase 2 — PREPARE
+
+### Git State
+
+```bash
+git branch --show-current
+git status --porcelain
+```
+
+### Branch Decision
+
+| Current State | Action |
+|---|---|
+| On feature branch | Use current branch |
+| On main, clean working tree | Create feature branch: `git checkout -b feat/{plan-name}` |
+| On main, dirty working tree | **STOP** — Ask user to stash or commit first |
+| In a git worktree for this feature | Use the worktree |
+
+### Sync Remote
+
+```bash
+git pull --rebase origin $(git branch --show-current) 2>/dev/null || true
+```
+
+**CHECKPOINT**: On correct branch. Working tree ready. Remote synced.
+
+---
+
+## Phase 3 — EXECUTE
+
+Process each task from the plan sequentially.
+
+### Per-Task Loop
+
+For each task in **Step-by-Step Tasks**:
+
+1. **Read MIRROR reference** — Open the pattern file referenced in the task's MIRROR field. Understand the convention before writing code.
+
+2. **Implement** — Write the code following the pattern exactly. Apply GOTCHA warnings. Use specified IMPORTS.
+
+3. **Validate immediately** — After EVERY file change:
+   ```bash
+   # Run type-check (adjust command per project)
+   [type-check command from Phase 0]
+   ```
+   If type-check fails → fix the error before moving to the next file.
+
+4. **Track progress** — Log: `[done] Task N: [task name] — complete`
+
+### Handling Deviations
+
+If implementation must deviate from the plan:
+- Note **WHAT** changed
+- Note **WHY** it changed
+- Continue with the corrected approach
+- These deviations will be captured in the report
+
+**CHECKPOINT**: All tasks executed. Deviations logged.
+
+---
+
+## Phase 4 — VALIDATE
+
+Run all validation levels from the plan. Fix issues at each level before proceeding.
+
+### Level 1: Static Analysis
+
+```bash
+# Type checking — zero errors required
+[project type-check command]
+
+# Linting — fix automatically where possible
+[project lint command]
+[project lint-fix command]
+```
+
+If lint errors remain after auto-fix, fix manually.
+
+### Level 2: Unit Tests
+
+Write tests for every new function (as specified in the plan's Testing Strategy).
+
+```bash
+[project test command for affected area]
+```
+
+- Every function needs at least one test
+- Cover edge cases listed in the plan
+- If a test fails → fix the implementation (not the test, unless the test is wrong)
+
+### Level 3: Build Check
+
+```bash
+[project build command]
+```
+
+Build must succeed with zero errors.
+
+### Level 4: Integration Testing (if applicable)
+
+```bash
+# Start server, run tests, stop server
+[project dev server command] &
+SERVER_PID=$!
+
+# Wait for server to be ready (adjust port as needed)
+SERVER_READY=0
+for i in $(seq 1 30); do
+  if curl -sf http://localhost:PORT/health >/dev/null 2>&1; then
+    SERVER_READY=1
+    break
+  fi
+  sleep 1
+done
+
+if [ "$SERVER_READY" -ne 1 ]; then
+  kill "$SERVER_PID" 2>/dev/null || true
+  echo "ERROR: Server failed to start within 30s" >&2
+  exit 1
+fi
+
+[integration test command]
+TEST_EXIT=$?
+
+kill "$SERVER_PID" 2>/dev/null || true
+wait "$SERVER_PID" 2>/dev/null || true
+
+exit "$TEST_EXIT"
+```
+
+### Level 5: Edge Case Testing
+
+Run through edge cases from the plan's Testing Strategy checklist.
+
+**CHECKPOINT**: All 5 validation levels pass. Zero errors.
+
+---
+
+## Phase 5 — REPORT
+
+### Create Implementation Report
+
+```bash
+mkdir -p .claude/PRPs/reports
+```
+
+Write report to `.claude/PRPs/reports/{plan-name}-report.md`:
+
+```markdown
+# Implementation Report: [Feature Name]
+
+## Summary
+[What was implemented]
+
+## Assessment vs Reality
+
+| Metric | Predicted (Plan) | Actual |
+|---|---|---|
+| Complexity | [from plan] | [actual] |
+| Confidence | [from plan] | [actual] |
+| Files Changed | [from plan] | [actual count] |
+
+## Tasks Completed
+
+| # | Task | Status | Notes |
+|---|---|---|---|
+| 1 | [task name] | [done] Complete | |
+| 2 | [task name] | [done] Complete | Deviated — [reason] |
+
+## Validation Results
+
+| Level | Status | Notes |
+|---|---|---|
+| Static Analysis | [done] Pass | |
+| Unit Tests | [done] Pass | N tests written |
+| Build | [done] Pass | |
+| Integration | [done] Pass | or N/A |
+| Edge Cases | [done] Pass | |
+
+## Files Changed
+
+| File | Action | Lines |
+|---|---|---|
+| `path/to/file` | CREATED | +N |
+| `path/to/file` | UPDATED | +N / -M |
+
+## Deviations from Plan
+[List any deviations with WHAT and WHY, or "None"]
+
+## Issues Encountered
+[List any problems and how they were resolved, or "None"]
+
+## Tests Written
+
+| Test File | Tests | Coverage |
+|---|---|---|
+| `path/to/test` | N tests | [area covered] |
+
+## Next Steps
+- [ ] Code review via `/code-review`
+- [ ] Create PR via `/prp-pr`
+```
+
+### Update PRD (if applicable)
+
+If this implementation was for a PRD phase:
+1. Update the phase status from `in-progress` to `complete`
+2. Add report path as reference
+
+### Archive Plan
+
+```bash
+mkdir -p .claude/PRPs/plans/completed
+mv "$ARGUMENTS" .claude/PRPs/plans/completed/
+```
+
+**CHECKPOINT**: Report created. PRD updated. Plan archived.
+
+---
+
+## Phase 6 — OUTPUT
+
+Report to user:
+
+```
+## Implementation Complete
+
+- **Plan**: [plan file path] → archived to completed/
+- **Branch**: [current branch name]
+- **Status**: [done] All tasks complete
+
+### Validation Summary
+
+| Check | Status |
+|---|---|
+| Type Check | [done] |
+| Lint | [done] |
+| Tests | [done] (N written) |
+| Build | [done] |
+| Integration | [done] or N/A |
+
+### Files Changed
+- [N] files created, [M] files updated
+
+### Deviations
+[Summary or "None — implemented exactly as planned"]
+
+### Artifacts
+- Report: `.claude/PRPs/reports/{name}-report.md`
+- Archived Plan: `.claude/PRPs/plans/completed/{name}.plan.md`
+
+### PRD Progress (if applicable)
+| Phase | Status |
+|---|---|
+| Phase 1 | [done] Complete |
+| Phase 2 | [next] |
+| ... | ... |
+
+> Next step: Run `/prp-pr` to create a pull request, or `/code-review` to review changes first.
+```
+
+---
+
+## Handling Failures
+
+### Type Check Fails
+1. Read the error message carefully
+2. Fix the type error in the source file
+3. Re-run type-check
+4. Continue only when clean
+
+### Tests Fail
+1. Identify whether the bug is in the implementation or the test
+2. Fix the root cause (usually the implementation)
+3. Re-run tests
+4. Continue only when green
+
+### Lint Fails
+1. Run auto-fix first
+2. If errors remain, fix manually
+3. Re-run lint
+4. Continue only when clean
+
+### Build Fails
+1. Usually a type or import issue — check error message
+2. Fix the offending file
+3. Re-run build
+4. Continue only when successful
+
+### Integration Test Fails
+1. Check server started correctly
+2. Verify endpoint/route exists
+3. Check request format matches expected
+4. Fix and re-run
+
+---
+
+## Success Criteria
+
+- **TASKS_COMPLETE**: All tasks from the plan executed
+- **TYPES_PASS**: Zero type errors
+- **LINT_PASS**: Zero lint errors
+- **TESTS_PASS**: All tests green, new tests written
+- **BUILD_PASS**: Build succeeds
+- **REPORT_CREATED**: Implementation report saved
+- **PLAN_ARCHIVED**: Plan moved to `completed/`
+
+---
+
+## Next Steps
+
+- Run `/code-review` to review changes before committing
+- Run `/prp-commit` to commit with a descriptive message
+- Run `/prp-pr` to create a pull request
+- Run `/prp-plan <next-phase>` if the PRD has more phases