autonomous-coding-toolkit 1.0.0

package/commands/run-plan.md

@@ -0,0 +1,117 @@
+---
+description: "Execute an implementation plan batch-by-batch with quality gates between each batch"
+argument-hint: "<plan-file> [--start-batch N] [--end-batch N] [--mode headless|team|competitive]"
+---
+
+# Run Plan
+
+Execute the implementation plan: $ARGUMENTS
+
+## How This Works
+
+You are orchestrating batch-by-batch execution of a markdown plan file. Each batch contains tasks that you implement sequentially using TDD, then a quality gate runs before proceeding to the next batch.
+
+## Step 1: Parse the Plan
+
+Read the plan file specified in the arguments. Extract:
+- All batches (lines matching `## Batch N: Title`)
+- Tasks within each batch (lines matching `### Task M: Name`)
+- Any metadata header (test baseline, quality gate command, tech stack)
+
+Report what you found:
+```
+Plan: <filename>
+Batches: N total
+Batch 1: <title> (M tasks)
+Batch 2: <title> (M tasks)
+...
+```
+
+If `--start-batch` or `--end-batch` were specified, note the execution range.
+
+## Step 2: Initialize State
+
+Create or read `.run-plan-state.json` in the current working directory:
+```json
+{
+  "plan_file": "<plan-file>",
+  "mode": "<mode>",
+  "current_batch": 1,
+  "completed_batches": [],
+  "test_counts": {},
+  "started_at": "<ISO timestamp>",
+  "last_quality_gate": null
+}
+```
+
+If the state file already exists and `--resume` was not specified, ask the user whether to resume or start fresh.
+
+## Step 3: Execute Batches
+
+For each batch in the execution range:
+
+### Mode: headless (default)
+Execute each task in the batch yourself using TDD:
+1. **Write a failing test** for the task
+2. **Run the test** — confirm it fails
+3. **Implement** the minimum code to pass
+4. **Run the test** — confirm it passes
+5. **Commit** the task with a descriptive message
+
+### Mode: team
+For each batch, spawn two agents:
+1. **Implementer** (general-purpose agent via Task tool) — receives the full batch text, implements using TDD
+2. **Reviewer** (code-reviewer agent via Task tool) — reviews the implementer's git diff against the batch spec
+
+If the reviewer finds issues, send fixes back to the implementer. Then run the quality gate.
+
+### Mode: competitive
+For critical batches (marked `⚠ CRITICAL` in the plan or specified via `--competitive-batches`):
+
+See `skills/autocode/competitive-mode.md` for the full competitive execution flow including:
+- Pre-flight exploration (codebase explorer + external research agents)
+- Competitor A (TDD) and Competitor B (Iterative) prompt templates
+- Judge scoring rubric with SCORE ANCHORS, structured checks, and hybrid evaluation
+- Mandatory best-of-both synthesis and loser merge
+- Cross-round learning (LESSONS FOR NEXT ROUND)
+
+Non-critical batches fall back to team mode.
+
+## Step 4: Quality Gate (after every batch)
+
+Run the quality gate between every batch. Default: `scripts/quality-gate.sh --project-root .`
+
+The quality gate checks:
+1. **Lesson check** — scan changed files for known anti-patterns
+2. **Test suite** — auto-detected (pytest / npm test / make test)
+3. **Memory check** — warn if < 4GB available
+
+Additionally check:
+- **Test count regression** — the number of passing tests must be >= the previous batch's count
+- **Git clean** — all changes must be committed
+
+If the quality gate fails:
+- Report what failed and why
+- Ask the user how to proceed (fix, skip, or abort)
+
+Update the state file after each batch completes.
+
+## Step 5: Summary
+
+After all batches complete, report:
+```
+Plan: <filename>
+Batches completed: N of M
+Test progression: 0 → 25 → 58 → 112
+Duration: <total time>
+Quality gates: all passed
+```
+
+## Rules
+
+- **TDD is mandatory.** Every task gets a failing test before implementation.
+- **Quality gates are mandatory.** Never skip to the next batch without passing.
+- **Test counts only go up.** If tests decrease, something broke — fix it.
+- **Commit after every task.** Small, atomic commits with descriptive messages.
+- **Update progress.txt** after each batch with a summary of what was done.
+- **Fresh context matters.** If you're past batch 5 and context feels degraded, suggest the user run `scripts/run-plan.sh --resume` headlessly for remaining batches.

package/commands/submit-lesson.md

@@ -0,0 +1,122 @@
+---
+description: "Submit a lesson learned from a bug you encountered — contributes back to the community"
+argument-hint: "[description of the bug or anti-pattern]"
+---
+
+# Submit Lesson
+
+Help the user capture a lesson learned and generate a PR against the autonomous-coding-toolkit repo.
+
+## Process
+
+### 1. Understand the Bug
+
+Ask the user what happened. If `$ARGUMENTS` is provided, use that as the starting description. Clarify:
+- What was the expected behavior?
+- What actually happened?
+- What code was involved? (file paths, snippets)
+- How long did it take to find the bug?
+
+### 2. Identify the Pattern
+
+Determine:
+- **Category:** async-traps | resource-lifecycle | silent-failures | integration-boundaries | test-anti-patterns | performance
+- **Severity:** blocker (data loss, crashes, silent corruption) | should-fix (subtle bugs, degraded behavior) | nice-to-have (code smell, future risk)
+- **Languages:** which languages this applies to (python, javascript, typescript, shell, all)
+
+### 3. Determine Check Type
+
+Is this pattern detectable by grep (syntactic) or does it need AI context (semantic)?
+
+**Syntactic** (grep-detectable, near-zero false positives):
+- Generate a `grep -P` regex that catches the anti-pattern
+- Test the regex against the user's actual code to verify it works
+- Verify it doesn't produce false positives on nearby code
+
+**Semantic** (needs context, AI-detectable):
+- Write a clear description of what to look for
+- Include a concrete bad/good example
+- The lesson-scanner agent will use this for contextual analysis
+
+### 4. Generate the Lesson File
+
+Auto-assign the next available ID:
+```bash
+# Find the highest existing ID
+max_id=$(ls docs/lessons/[0-9]*.md 2>/dev/null | sed 's/.*\///' | sed 's/-.*//' | sort -n | tail -1)
+next_id=$(printf "%04d" $((10#${max_id:-0} + 1)))
+```
+
+Generate slug from title (lowercase, hyphens, no special chars).
+
+Write the lesson file using this schema:
+
+```yaml
+---
+id: <next_id>
+title: "<concise title>"
+severity: <blocker|should-fix|nice-to-have>
+languages: [<list>]
+category: <category>
+pattern:
+  type: <syntactic|semantic>
+  regex: "<grep -P pattern>"     # Only for syntactic
+  description: "<what to look for>"
+fix: "<how to fix it>"
+example:
+  bad: |
+    <code that demonstrates the anti-pattern>
+  good: |
+    <code that demonstrates the fix>
+---
+
+## Observation
+<What happened — factual description>
+
+## Insight
+<Why it happened — root cause>
+
+## Lesson
+<The rule to follow going forward>
+```
+
+### 5. Save and Offer Contribution
+
+Save to `docs/lessons/<next_id>-<slug>.md`.
+
+Show the user the generated file and ask:
+
+**Option A: Save locally only**
+- File is saved in the current project's `docs/lessons/` directory
+- Available to their local lesson-check.sh and lesson-scanner
+
+**Option B: Submit as PR to the toolkit repo**
+- Fork the toolkit repo if needed: `gh repo fork parthalon025/autonomous-coding-toolkit --clone=false`
+- Create a branch: `lesson/<id>-<slug>`
+- Commit the lesson file
+- Open a PR:
+  ```bash
+  gh pr create --repo parthalon025/autonomous-coding-toolkit \
+    --title "lesson: <title>" \
+    --body "## New Lesson
+
+  **Category:** <category>
+  **Severity:** <severity>
+  **Pattern type:** <syntactic|semantic>
+
+  ## What this catches
+  <description>
+
+  ## How it was discovered
+  <user's bug description>
+  "
+  ```
+
+## Quality Bar
+
+Before submitting, verify:
+- [ ] The regex (if syntactic) catches the bad example
+- [ ] The regex does NOT match the good example
+- [ ] The description is clear enough for the lesson-scanner to use
+- [ ] The fix is actionable (not just "be careful")
+- [ ] The example is realistic (from real code, anonymized)