cc-codeconductor 1.1.0 → 1.3.0

package/presets/codex/skills/cc-tdd-cycle/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: cc-tdd-cycle
+description: Run a structured Red-Green-Refactor TDD cycle — write a failing test first, implement the minimum code to pass it, then refactor with the suite green.
+---
+
+# tdd-cycle
+
+Invoke as `$cc-tdd-cycle`. The user request follows the skill mention.
+
+# TDD Cycle — Red → Green → Refactor
+
+Scope: $ARGUMENTS
+
+Describe what behavior you want to implement. Include:
+
+- The function, method, or feature to implement
+- The expected behavior (inputs and outputs, or acceptance criteria)
+- Any known constraints or edge cases
+- Relevant files or modules (if known)
+
+---
+
+## Step 0 — CCEP Bootstrap
+
+Command: `tdd-cycle` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command tdd-cycle "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command tdd-cycle "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile tdd-cycle --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command tdd-cycle --input <planner.json> --output json`. If `stop` is true, show questions or risks and wait for human input.
+5. Delegate to subagents using compiled CCEP prompts — never forward raw `$ARGUMENTS` to planners.
+   Canonical delivery order is test-before-implement whenever both phases apply.
+
+---
+
+## Step 0b — OpenSpec quality gates
+
+If `openspec status` reports an active change folder:
+
+1. Run: `npx cc-codeconductor openspec validate --output json`
+2. Run: `npx cc-codeconductor openspec analyze --output json`
+3. If analyze `stop` is true or any finding is CRITICAL, stop. Do not delegate to implementer.
+4. Next command spelling on this runner: `$cc-tdd-cycle`
+
+Local development: `bun run dev <same argv>`. Published package: `npx cc-codeconductor`.
+
+---
+
+
+## Before you begin — mandatory pre-check
+
+This command enforces strict TDD discipline. The three phases are sequential and
+non-negotiable:
+
+1. **RED** — a failing test exists before any implementation code is written
+2. **GREEN** — the minimum implementation to make the test pass (no more)
+3. **REFACTOR** — clean up the code while keeping all tests green
+
+Do not write implementation code during RED. Do not refactor during GREEN.
+Mixing phases invalidates the cycle.
+
+## Verifiable phase gates
+
+RED → GREEN and GREEN → REFACTOR are enforced by `tddCycleStateMachine` in
+`domain/loop`. Evidence must be captured with `captureTddSuiteEvidence` (verification
+runner) — do not hand-edit JSON under `.codeconductor/evidence/`.
+
+- RED→GREEN requires runner evidence that the suite **failed**.
+- GREEN→REFACTOR requires runner evidence that the suite **passed**.
+
+Do not advance phases until that evidence exists.
+
+---
+
+## Phase 1 — RED (Tester role)
+
+Adopt the `tester` role as defined in `AGENTS.md`.
+
+### 1a — Scope clarification
+
+Before writing any test, confirm:
+
+- What is the unit of behavior being tested? (function, method, endpoint, domain
+  rule)
+- What are the inputs and expected outputs?
+- What are the failure cases?
+
+If the scope is ambiguous, ask one clarifying question and wait for the answer.
+
+### 1b — Write the failing test
+
+Write a test that:
+
+- Targets exactly the behavior described in the scope
+- Fails for the right reason (not a compile error, not a missing dependency —
+  the logic does not exist yet)
+- Has a name that describes the behavior: `given_X_when_Y_then_Z` or equivalent
+  in the project's test naming convention
+- Covers at minimum: one happy path, one edge case, one failure case
+
+Do not write the implementation. Do not make the test pass by any means other
+than the implementation that will follow in Phase 2.
+
+### 1c — Run the test suite and confirm RED
+
+Run the test suite. The new test must fail. Existing tests must pass.
+
+If the new test passes without implementation, the test is wrong. Fix the test
+before continuing.
+
+**RED Phase Report:**
+
+```
+## RED Phase Report
+
+**Test file**: [path/to/test/file]
+**Tests written**:
+- [test name] — [what it verifies]
+
+**Suite result**: [X passing, Y failing]
+**New test status**: FAIL ✓
+**Failure reason**: [quoted error or assertion message]
+**Existing tests**: [all passing | N failing — list]
+```
+
+**STOP. Show the RED Phase Report. Do not proceed to GREEN without
+confirmation.**
+
+---
+
+## Phase 2 — GREEN (Implementer role)
+
+Adopt the `implementer` role as defined in `AGENTS.md`.
+
+### 2a — Read the failing test before writing any code
+
+Understand exactly what the test asserts. Write only the code that satisfies
+that assertion. Nothing more.
+
+### 2b — Implement the minimum
+
+Rules for GREEN phase:
+
+- Write the smallest amount of code that makes the failing test pass
+- Do not add features not tested
+- Do not clean up or restructure existing code — that is Refactor's job
+- Do not add new tests — that is another RED cycle
+- Hardcoding a return value is acceptable if it makes the test pass (the
+  Refactor phase will generalize it)
+
+### 2c — Run the test suite and confirm GREEN
+
+Run the test suite. The new test must pass. All previously passing tests must
+still pass.
+
+If any previously passing test now fails, you introduced a regression. Fix it
+before continuing.
+
+**GREEN Phase Report:**
+
+```
+## GREEN Phase Report
+
+**Files changed**:
+- [path/to/file] — [what was added, one sentence]
+
+**Implementation approach**: [one sentence — what the code does]
+**Suite result**: [X passing, Y failing]
+**New test status**: PASS ✓
+**Regressions**: [none | list failing tests]
+```
+
+**STOP. Show the GREEN Phase Report. Do not proceed to REFACTOR without
+confirmation.**
+
+---
+
+## Phase 3 — REFACTOR (Implementer role, then Reviewer role)
+
+Adopt the `implementer` role as defined in `AGENTS.md`.
+
+### 3a — Assess what needs cleaning
+
+Before touching any code, identify:
+
+- Duplication introduced during GREEN
+- Names that do not clearly express intent
+- Abstractions that belong in a separate function or module
+- Logic that is hardcoded and should be generalized
+
+Do not invent improvements. Only address what is directly in the implementation
+written in Phase 2.
+
+### 3b — Refactor
+
+Rules for REFACTOR phase:
+
+- All tests must remain GREEN throughout — run the suite after each change
+- Do not add new behavior
+- Do not add new tests (if you discover untested behavior, note it for a new RED
+  cycle)
+- Do not change function signatures unless the original was clearly wrong
+
+### 3c — Run the test suite and confirm GREEN after refactor
+
+The full suite must pass. If any test fails during refactor, undo the last
+change and investigate.
+
+### 3d — Review (Reviewer role)
+
+Adopt the `reviewer` role as defined in `AGENTS.md`.
+
+Review only the refactored code against these axes:
+
+| Axis          | What to check                                                   |
+| ------------- | --------------------------------------------------------------- |
+| Scope         | Did the refactor change any behavior?                           |
+| Correctness   | Does the logic still satisfy the original test intent?          |
+| Architecture  | Does the code follow existing project patterns?                 |
+| Test coverage | Are all written tests still meaningful (not trivially passing)? |
+
+Produce a Review Report. CRITICAL findings block completion.
+
+**REFACTOR Phase Report:**
+
+```
+## REFACTOR Phase Report
+
+**Changes made**:
+- [path/to/file] — [what was cleaned up]
+
+**Suite result**: [X passing, Y failing]
+**Behavioral changes**: none (refactor only)
+
+### Review findings
+**CRITICAL**: (none) | [list]
+**WARNING**: (none) | [list]
+**SUGGESTION**: (none) | [list]
+
+**Verdict**: approved | approved with warnings | blocked
+```
+
+---
+
+## Completion
+
+The TDD cycle is complete when:
+
+- RED: at least one failing test was written and confirmed failing
+- GREEN: the minimum implementation makes the test pass
+- REFACTOR: the code is clean, all tests pass, no CRITICAL review findings
+
+**Final Summary:**
+
+```
+## TDD Cycle Summary
+
+**Behavior implemented**: [one sentence]
+**Tests written**: [count] — [list test names]
+**Files changed**: [list]
+**Suite result**: [X passing, Y failing]
+**Cycle status**: complete | blocked (reason)
+```
+
+If the behavior requires additional test cases, start a new `/tdd-cycle` with
+the next scenario. One cycle = one behavior.

package/presets/codex/skills/cc-test-plan/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: cc-test-plan
+description: Generate a structured test plan for a feature or module — covers unit, integration, contract, and edge cases without writing implementation code.
+---
+
+# test-plan
+
+Invoke as `$cc-test-plan`. The user request follows the skill mention.
+
+# Test Plan Workflow
+
+Scope: $ARGUMENTS
+
+Specify what to plan tests for. Examples:
+
+- A feature name: `user authentication`
+- A module or file path: `src/orders/OrderService.kt`
+- A Task Card title: `Add paginated product listing endpoint`
+- A PR or branch: `feature/payment-retry`
+
+If $ARGUMENTS is empty, describe the scope in your next message before
+proceeding.
+
+---
+
+## Step 0 — CCEP Bootstrap
+
+Command: `test-plan` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command test-plan "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command test-plan "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile test-plan --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command test-plan --input <planner.json> --output json`. If `stop` is true, show questions or risks and wait for human input.
+5. Delegate to subagents using compiled CCEP prompts — never forward raw `$ARGUMENTS` to planners.
+
+---
+
+## Step 1 — Scope confirmation
+
+Before generating the test plan, confirm the scope is well-defined.
+
+A valid scope includes:
+
+- The behavior or module under test
+- The acceptance criteria or expected behavior (from the Task Card if available)
+- Known edge cases or failure modes
+
+If the scope is vague (e.g., "test the whole service"), ask one clarifying
+question and wait for the answer.
+
+---
+
+## Step 2 — Test plan generation (Tester role, planning mode)
+
+Adopt the `tester` role as defined in `AGENTS.md`.
+
+Produce a test plan document — not test code. The plan will be used as input
+when tests are actually written.
+
+Cover the following layers:
+
+**Unit tests**
+
+- Individual functions or methods in isolation
+- One test per behavior, not per method
+- Input/output contracts, null handling, type coercion
+
+**Integration tests**
+
+- Interactions between two or more components
+- Database read/write cycles (if applicable)
+- External service boundaries (mocked or stubbed)
+
+**Contract tests**
+
+- API endpoint contracts: request shape, response shape, status codes
+- Event schema contracts (if event-driven components are in scope)
+
+**Edge cases**
+
+- Empty inputs, boundary values, max/min limits
+- Concurrent access (if shared state is involved)
+- Failure paths: what happens when a dependency is unavailable
+
+**Regression cases**
+
+- Known past bugs that must not recur (include reference if available)
+
+---
+
+## Step 3 — Test Plan format
+
+Produce the plan in this format:
+
+```markdown
+## Test Plan — [Scope Name]
+
+### Scope
+[What is being tested and why]
+
+### Unit Tests
+| Test ID | Target | Scenario | Expected Result |
+| ------- | ------ | -------- | --------------- |
+| U-001   | ...    | ...      | ...             |
+
+### Integration Tests
+| Test ID | Components | Scenario | Expected Result |
+| ------- | ---------- | -------- | --------------- |
+| I-001   | ...        | ...      | ...             |
+
+### Contract Tests
+| Test ID | Endpoint/Event | Property | Expected Value |
+| ------- | -------------- | -------- | -------------- |
+| C-001   | ...            | ...      | ...            |
+
+### Edge Cases
+| Test ID | Input/Condition | Expected Behavior |
+| ------- | --------------- | ----------------- |
+| E-001   | ...             | ...               |
+
+### Regression Cases
+| Test ID | Reference | Scenario | Must Not Happen |
+| ------- | --------- | -------- | --------------- |
+| R-001   | ...       | ...      | ...             |
+
+### Coverage Targets
+- Minimum unit coverage: [% or "all acceptance criteria covered"]
+- Integration scenarios: [count]
+- Contract validations: [count]
+
+### Out of Scope
+[What this test plan explicitly does not cover and why]
+```
+
+---
+
+## Step 4 — Human review
+
+Show the Test Plan before any tests are written. The Test Plan is an artifact
+for review and approval.
+
+Writing test code is a separate action — run `/feature` or add a test task to
+implement from this plan.
+
+---
+
+## Completion
+
+Deliver the complete Test Plan document. Save it as
+`docs/test-plans/[scope-slug].md` if requested.
+
+This command produces a plan, not test files. No production code and no test
+code is written during this command.
+
+## Next
+
+Implement against this plan with `$cc-tdd-cycle` or `$cc-feature`.

package/presets/codex/skills/cc-triage/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: cc-triage
+description: Classify a request into type, risk, and the destination CodeConductor command.
+---
+
+# triage
+
+Invoke as `$cc-triage`. The user request follows the skill mention.
+
+# Triage Workflow
+
+Triage request: $ARGUMENTS
+
+## Step 0 — CCEP Bootstrap
+
+Command: `triage` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command triage "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command triage "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile triage --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command triage --input <planner.json> --output json`. If `stop` is true, show questions or risks and wait for human input.
+5. Delegate to subagents using compiled CCEP prompts — never forward raw `$ARGUMENTS` to planners.
+
+---
+
+## Step 1 — Classify (task-coach)
+
+Invoke `task-coach`. Produce: title, type (`feature` | `fix` | `refactor` | `review` | `docs` | `test`), risk, named scope, and the destination command (`feature`, `fix`, `refactor`, `review`, `explore`, …).
+
+Ask one question per unresolved branch. If the human is unavailable, emit a Markdown questionnaire and stop at ConfirmationGate.
+
+**STOP here. Show the classification and wait for confirmation before running the destination workflow.**
+
+---
+
+## Completion
+
+Do not implement. Hand the human a destination slash command and a partial Task Card.

package/presets/codex/skills/django-orm/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: django-orm
-version: 1.0.0
 name: Django ORM
 description: >
   Django ORM patterns for multi-tenant POS projects: efficient queries,

package/presets/codex/skills/django-testing/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: django-testing
-version: 1.0.0
 name: Django Testing
 description: >
   Testing patterns for multi-tenant Django POS projects using pytest-django,

package/presets/codex/skills/evaluation/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: evaluation
+description:
+  Guides agents through scorecards, outcomes, model profiles, and eval suites.
+  Use when running /cc-scorecard or /cc:scorecard, measuring a deliverable, or
+  checking workflow gates with suite-run.
+---
+
+# Evaluation
+
+## Overview
+
+A scorecard measures the deliverable against eight weighted criteria. Spec
+quality checklists are reviewer-owned. "Seems right" is not a verdict.
+
+Pass threshold: weighted score >= 2.0 and no criterion at 0.
+
+## When to Use
+
+- After implement/review, before `openspec archive`
+- Comparing models or prompt versions
+- Proving the workflow tools still work (`suite-run`)
+
+**NOT** for rewriting specs (reviewer checklist) or for implementing code.
+
+## Process
+
+Local: `bun run dev`. Published: `npx cc-codeconductor`.
+
+```text
+scorecard create --task BC-001 --from-diff
+scorecard record --task BC-001 --verdict PASS --score 2.5
+scorecard list | aggregate | models | regression | matrix | compare-models
+scorecard prompt-diff 0.4.0 0.5.0 --agent architect
+scorecard experiment start --suite harness-v1
+scorecard suite-run --suite workflow-gates
+scorecard suite-run --suite hook-guardrails
+scorecard suite-run --suite scorecard-signals
+```
+
+`openspec analyze` can auto-suggest `acceptance` / `tests` on `--from-diff`.
+Archive needs PASS when review is required.
+
+Outcomes append to `.codeconductor/evaluation/outcomes.jsonl`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| I'll fill the scorecard by hand without a diff | Use `--from-diff` and runner evidence. |
+| Suites are optional toys | `suite-run` is the workflow tool that proves gates. |
+| Handmade TDD JSON is fine | The runner rejects it. |
+
+## Red Flags
+
+- PASS with a criterion at 0
+- Archive without a recorded scorecard when review is required
+- Declaring the workflow ready without `suite-run` or `scorecard record`
+
+## Verification
+
+- [ ] Scorecard created from diff (or explicit scores)
+- [ ] Verdict PASS / REVISE / REJECT recorded
+- [ ] For process changes: `scorecard suite-run --suite hook-guardrails` (and
+      `workflow-gates` / `scorecard-signals` when those gates changed)

package/presets/codex/skills/jpa-postgres/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: jpa-postgres
-version: 1.0.0
 name: JPA + PostgreSQL
 description: >
   Provides expert knowledge of JPA entity design, relationship mapping, Flyway

package/presets/codex/skills/openspec/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: openspec
+description:
+  Guides agents through OpenSpec delivery from BACKLOG.md (validate, analyze,
+  test-before-implement, scorecard, archive). Use when running /cc-openspec,
+  /cc:openspec, or delivering an existing backlog item. Authoring BACKLOG.md
+  is skill backlog, not this skill.
+---
+
+# OpenSpec delivery
+
+## Overview
+
+This skill delivers an existing `BACKLOG.md` item. It is a workflow with CLI
+gates, not a reference doc. Specs describe WHAT; `design.md` describes HOW.
+
+## When to Use
+
+- `/cc-openspec` or `openspec next` / `plan` / `done` / `archive`
+- An item is `READY` or later and must move through the state machine
+
+**NOT** for creating `BACKLOG.md` (use skill `backlog`) or for stack-specific
+coding rules.
+
+## Process
+
+Local CLI is `bun run dev`. Published package is `npx cc-codeconductor`.
+
+1. `openspec validate` — must pass before delivery.
+2. `openspec plan BC-xxx` if the item is not yet `PLANNED`.
+3. `openspec analyze --output json` — CRITICAL findings exit 1. Do not implement.
+4. Phases: discover (`repo-explorer`) → design (`architect`) → test (`tester`) →
+   implement (`implementer`) → review (`reviewer`). If Global `TDD required: yes`,
+   test runs before implement.
+5. `openspec done` on test/implement requires `captureTddSuiteEvidence`. Handmade
+   evidence JSON is rejected.
+6. `scorecard create --task BC-xxx --from-diff` then record a verdict.
+7. `openspec archive` only after human review when `Review required: yes` and
+   the scorecard is PASS.
+
+Status machine: `TODO` → `READY` → `PLANNED` → `IN_PROGRESS` → `REVIEW` → `DONE`
+→ Archive. `BLOCKED` returns to `READY`. Reviewer rejection: `REVIEW` →
+`IN_PROGRESS`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| Validate is bureaucracy | `openspec validate` is the gate. Skipping it is a defect. |
+| I'll add tests after green | Global TDD required means tester before implementer. |
+| I'll write the evidence JSON myself | Handmade TDD JSON is rejected. Use the verification runner. |
+| The item is small; skip analyze | `openspec analyze` CRITICAL still stops implement. |
+
+## Red Flags
+
+- Implementing while analyze reports CRITICAL
+- Archive without a PASS scorecard when review is required
+- Acceptance like "improve UX" with no measurable check
+
+## Verification
+
+- [ ] `openspec validate` exit 0
+- [ ] `openspec analyze --output json` has no CRITICAL
+- [ ] TDD evidence from the runner when TDD is required
+- [ ] `scorecard create --from-diff` recorded
+- [ ] Suite check (optional): `bun run dev scorecard suite-run --suite workflow-gates`

package/presets/codex/skills/pagespeed-perf/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: pagespeed-perf
-version: 1.0.0
 name: PageSpeed Performance Audit
 description: >
   Web Performance Engineering — analyzes Core Web Vitals using the PageSpeed
@@ -32,7 +31,7 @@ inputs:
   - name: url
     type: string
     required: true
-    description: Full URL to audit (must include scheme: https://...)
+    description: "Full URL to audit (must include scheme: https://...)"
   - name: strategy
     type: string
     required: false

package/presets/codex/skills/python/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: python
-version: 1.0.0
 name: Python
 description: >
   Python development best practices: clean code, patterns,

package/presets/codex/skills/python-django-stack/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: python-django-stack
-version: 1.0.0
 name: Python Django Stack
 description: >
   Python and Django conventions for multi-tenant SaaS POS projects:

package/presets/codex/skills/python-fastapi-stack/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: python-fastapi-stack
-version: 1.0.0
 name: Python FastAPI Stack
 description: >
   FastAPI conventions for REST APIs: routers, Pydantic v2 schemas, dependency

package/presets/codex/skills/spring-boot-feature/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: spring-boot-feature
-version: 1.0.0
 name: Spring Boot Feature Creation
 description: >
   Guides the creation of complete Spring Boot features following a structured,

package/presets/codex/skills/spring-boot-kotlin/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: spring-boot-kotlin
-version: 1.0.0
 name: Spring Boot + Kotlin
 description: >
   Provides expert knowledge of Spring Boot conventions, Kotlin idioms, and MVC

package/presets/codex/skills/sqlalchemy/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: sqlalchemy
-version: 1.0.0
 name: SQLAlchemy
 description: >
   SQLAlchemy 2.x patterns for async FastAPI projects: models, sessions, queries,

package/presets/codex/skills/testing-strategy/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: testing-strategy
-version: 1.0.0
 name: Testing Strategy
 description: >
   Provides expert knowledge of the testing pyramid, test design principles,