ancoder-skill-cli 0.6.4 → 0.7.1

package/README.md

@@ -84,6 +84,121 @@ my-skill/
 
 Users who `npm install -g ancoder-skill-cli` get a fully bundled package. No extra binary download is required during install.
 
+## Test-Driven Skill Development (100:10:1 Architecture)
+
+skill-cli adopts a test-driven approach to skill development, inspired by [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)'s multi-agent orchestration patterns. The core principle: **invest the majority of compute in building robust test skills, not the skill itself.**
+
+### Time Allocation: 100:10:1
+
+When creating a skill for a task, the system simultaneously creates a **main skill** and a **test skill**:
+
+| Phase | Time Share | Purpose |
+|-------|-----------|---------|
+| Test skill development | 90% (100 units) | Build an automated evaluator that compares expected vs actual output, locating specific differences |
+| Main skill development | 9% (10 units) | Implement the actual skill, guided by test skill feedback |
+| Execution & verification | 1% (1 unit) | Final end-to-end smoke test |
+
+### Architecture
+
+```text
+Phase 1: Test Skill Development (90% compute)
+  generate structured acceptance criteria
+  -> N planners generate test strategies in parallel
+  -> critic reviews + eliminates weak strategies
+  -> N executors implement test skills in parallel
+  -> golden test evaluation (tournament selection)
+  -> repeat until precision threshold met
+  -> best test skill selected
+
+Phase 2: Main Skill Development (9% compute)
+  generate main skill
+  -> test skill verifies (independent executor)
+  -> structured diff feedback injected into next prompt
+  -> repeat until test skill passes
+  -> main skill complete
+
+Phase 3: Final Verification (1% compute)
+  end-to-end smoke test
+```
+
+### Key Design Principles
+
+**1. Separation of Author and Reviewer**
+
+The agent that generates the main skill and the agent that runs the test skill operate in separate contexts. This prevents self-approval bias. The verify phase spawns an independent executor to run the test skill, ensuring honest evaluation (borrowed from OMC's verifier lane pattern).
+
+**2. Structured Diff Feedback**
+
+Test skills output structured diff reports instead of simple pass/fail:
+
+```yaml
+diffs:
+  - location: "page 3, paragraph 2"
+    type: "content_loss"
+    severity: "critical"
+    expected: "table with 3 columns and 5 rows"
+    actual: "table missing entirely"
+  - location: "page 5, heading"
+    type: "format_drift"
+    severity: "warning"
+    expected: "## Second-level heading"
+    actual: "### Third-level heading"
+```
+
+This structured feedback is injected back into the main skill's improvement loop, enabling targeted fixes rather than blind retries.
+
+**3. QA Cycling with Early Exit**
+
+Borrowed from OMC's UltraQA pattern:
+- Test skill finds issues -> structured diagnosis -> main skill fixes -> retest -> loop
+- Same error appearing 3 times triggers early exit (avoids infinite compute burn)
+- Maximum 5 QA cycles per iteration
+
+**4. Tournament Selection for Test Skills**
+
+During the 90% test skill development phase, multiple test strategies are generated in parallel and evaluated against golden tests (known-correct input/output pairs). The strategy with the highest detection precision wins, similar to OMC's self-improve tournament selection.
+
+**5. PRD-Driven Acceptance Criteria**
+
+Test skills define concrete, testable acceptance criteria (not vague "implementation is complete"):
+
+```text
+Bad:  "PDF conversion works correctly"
+Good: "All tables with merged cells are preserved as HTML <table> blocks
+       with correct colspan/rowspan attributes"
+```
+
+### Example: PDF-to-Markdown Skill
+
+For a PDF-to-Markdown conversion skill:
+
+- **Test skill** (100 min): Compares original PDF content with generated Markdown, detecting content loss (missing paragraphs, tables, images), format drift (heading levels, list styles), and encoding issues. Outputs structured diffs with page/paragraph-level location info.
+- **Main skill** (10 min): Implements PDF parsing and Markdown generation, iteratively improved by test skill feedback.
+- **Verification** (1 min): End-to-end smoke test on fixture PDFs.
+
+### `skill_eval` Check Type
+
+The verify system supports a `skill_eval` check type that invokes a test skill as a verification oracle:
+
+```yaml
+checks:
+  - id: quality-check
+    type: skill_eval
+    skill: pdf-to-md-test
+    config:
+      threshold: 0.95
+      output_format: structured_diff
+```
+
+### Verify Phase: Independent Executor
+
+During the loop's verify phase, a separate Claude executor is spawned to run the test skill. This executor:
+- Has no shared context with the main skill's executor
+- Produces an objective evaluation report
+- Returns structured diff feedback that feeds into the next iteration
+
+This mirrors OMC's principle: "Keep authoring and review as separate passes."
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ancoder-skill-cli",
-  "version": "0.6.4",
+  "version": "0.7.1",
   "description": "CLI for managing everything-claude-code (ECC) components — agents, skills, commands, rules, hooks, MCP configs. Single binary, all assets embedded.",
   "bin": {
     "skill-cli": "bin/skill-cli.js"