cc-codeconductor 1.2.0 → 1.4.0

package/docs/generated/cli.md

@@ -0,0 +1,202 @@
+# CodeConductor CLI
+
+## setup
+
+Configure and install CodeConductor.
+
+```text
+cc setup [--target <target>] [--locale en|es] [--yes] [--dry-run]
+```
+
+## detect
+
+Inspect the project stack and recommended presets.
+
+```text
+cc detect
+```
+
+## init
+
+Initialize low-level CodeConductor configuration.
+
+```text
+cc init [--locale en|es]
+```
+
+## install
+
+Install harness components.
+
+```text
+cc install preset --target <target>
+```
+
+## version
+
+Show CLI and project harness versions.
+
+```text
+cc version [--json]
+```
+
+## status
+
+Show installed harness state.
+
+```text
+cc status [--json]
+```
+
+## doctor
+
+Diagnose the installation.
+
+```text
+cc doctor
+```
+
+## update
+
+Safely reconcile managed harness files.
+
+```text
+cc update [--dry-run] [--force]
+```
+
+## migrate
+
+Apply compatibility migrations.
+
+```text
+cc migrate [--dry-run]
+```
+
+## docs
+
+Read bundled command documentation.
+
+```text
+cc docs [command]
+```
+
+## completion
+
+Generate shell completion.
+
+```text
+cc completion <bash|zsh|fish|powershell>
+```
+
+## hook
+
+Run installed agent hooks.
+
+```text
+cc hook <pre-tool|post-tool|session-start>
+```
+
+## cc-help
+
+Show a target preset inventory.
+
+```text
+cc cc-help --target <target>
+```
+
+## ask
+
+Recommend a slash-command workflow.
+
+```text
+cc ask "problem"
+```
+
+## goal
+
+Plan a goal into dependent tasks.
+
+```text
+cc goal "objective"
+```
+
+## ingest
+
+Ingest repository knowledge into the product graph.
+
+```text
+cc ingest
+```
+
+## product
+
+Explore the product graph and memory.
+
+```text
+cc product <subcommand>
+```
+
+## ccep
+
+Run CCEP contract workflows.
+
+```text
+cc ccep <subcommand>
+```
+
+## openspec
+
+Run the OpenSpec delivery loop.
+
+```text
+cc openspec <subcommand>
+```
+
+## scorecard
+
+Record and aggregate outcomes.
+
+```text
+cc scorecard <subcommand>
+```
+
+## orchestrate
+
+Run goal execution orchestration.
+
+```text
+cc orchestrate <subcommand>
+```
+
+## impact
+
+Analyze change impact.
+
+```text
+cc impact [--files <paths>]
+```
+
+## verify
+
+Verify task completion with evidence.
+
+```text
+cc verify --task <id>
+```
+
+## seo
+
+Audit SEO and generate llms.txt.
+
+```text
+cc seo audit --url <url>
+```
+
+## debt-harvest
+
+Scan source files for deferred debt.
+
+```text
+cc debt-harvest
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-codeconductor",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "A multi-agent orchestration framework for AI-assisted software engineering workflows.",
   "keywords": [
     "ai",
@@ -18,6 +18,7 @@
     "dist/index.js",
     "dist/library.js",
     "dist/**/*.d.ts",
+    "docs/generated/",
     "policy.yml",
     "presets/",
     "src/presets/"
@@ -48,12 +49,16 @@
     "build:cli": "bun build src/cli/main.ts --target=node --outfile=dist/index.js",
     "build:lib": "bun build src/index.ts --target=node --outfile=dist/library.js --packages=external",
     "build:types": "tsc -p tsconfig.lib.json --emitDeclarationOnly",
+    "generate:cli-docs": "bun run scripts/generate-cli-docs.ts",
     "test": "bun test",
     "test:fast": "bun run scripts/test-fast.ts",
     "typecheck": "tsc --noEmit",
     "lint": "bun run scripts/lint.ts",
     "check:coverage": "bun run scripts/check-coverage.ts",
     "check:prompt-changelog": "bun run scripts/check-prompt-changelog.ts",
+    "check:drift": "bun run scripts/check-drift.ts",
+    "render:commands": "bun run scripts/render-agent-commands.ts",
+    "sync:skills": "bun run scripts/sync-shared-skills.ts",
     "release:patch": "bash release.sh patch",
     "release:minor": "bash release.sh minor",
     "release:major": "bash release.sh major",

package/presets/agy/AGENTS.md

@@ -76,7 +76,7 @@ Antigravity CLI loads custom slash commands from `.agents/workflows/*.md`. The f
 | `/cc-api-contract`| Handles API contract modification and validation                  |
 | `/cc-db-migration`| Coordinates database schema migrations safely                      |
 | `/cc-iterative`  | Advanced iterative workflow — wayfinding, grilling, TDD, council |
-| `/cc-explore`    | Map the repo and recommend the next `/cc:` command               |
+| `/cc-explore`    | Map the repo and recommend the next `/cc-` command               |
 | `/cc-triage`     | Classify type, risk, and destination workflow                    |
 | `/cc-prototype`  | Disposable spike in an isolated worktree                         |
 | `/cc-handoff`    | Compact the session to `.codeconductor/` Markdown                |

package/presets/agy/hooks.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"const fs=require('fs'),p=['scripts/invoke-hook.cjs','.agents/scripts/invoke-hook.cjs'].find(f=>fs.existsSync(f));if(p)require(require('path').resolve(p));else{if(process.argv.includes('--format=agy')){process.stdout.write(process.argv.includes('post-tool')?'{}\\n':'{\\\"decision\\\":\\\"allow\\\"}\\n');}process.exit(0);}\" post-tool --format=agy"
+            "command": "node -e \"const fs=require('fs');const c=['scripts/invoke-hook.cjs','.agents/scripts/invoke-hook.cjs'];const p=c.find(f=>fs.existsSync(f));if(p){require(require('path').resolve(p));}else{const body=process.argv.includes('post-tool')?{}:{decision:'allow'};process.stdout.write(JSON.stringify(body)+'\\n');process.exit(0);}\" post-tool --format=agy"
           }
         ]
       }
@@ -17,11 +17,11 @@
     "enabled": true,
     "PreToolUse": [
       {
-        "matcher": "run_command|write_to_file|replace_file_content|multi_replace_file_content|view_file",
+        "matcher": "run_command|write_to_file|replace_file_content|multi_replace_file_content",
         "hooks": [
           {
             "type": "command",
-            "command": "node -e \"const fs=require('fs'),p=['scripts/invoke-hook.cjs','.agents/scripts/invoke-hook.cjs'].find(f=>fs.existsSync(f));if(p)require(require('path').resolve(p));else{if(process.argv.includes('--format=agy')){process.stdout.write(process.argv.includes('post-tool')?'{}\\n':'{\\\"decision\\\":\\\"allow\\\"}\\n');}process.exit(0);}\" pre-tool --format=agy"
+            "command": "node -e \"const fs=require('fs');const c=['scripts/invoke-hook.cjs','.agents/scripts/invoke-hook.cjs'];const p=c.find(f=>fs.existsSync(f));if(p){require(require('path').resolve(p));}else{const body=process.argv.includes('post-tool')?{}:{decision:'allow'};process.stdout.write(JSON.stringify(body)+'\\n');process.exit(0);}\" pre-tool --format=agy"
           }
         ]
       }

package/presets/agy/scripts/invoke-hook.cjs

@@ -41,33 +41,33 @@ function findProjectRoot() {
 
 const projectRoot = findProjectRoot();
 
-function canRun(bin) {
-  try {
-    const result = spawnSync(bin, ['--version'], {
-      encoding: 'utf8',
-      windowsHide: true,
-      stdio: 'ignore',
-      timeout: SPAWN_TIMEOUT,
-    });
-    return result.status === 0;
-  } catch {
-    return false;
-  }
-}
-
+/**
+ * Run one candidate runner. Stdout/stderr are captured (not inherited) so a
+ * candidate that writes partial output before failing can never leak onto
+ * this process's real stdout ahead of a later candidate's output or the
+ * fallback JSON — every event this process ever emits on stdout must be a
+ * single clean document. Stderr is diagnostic-only and safe to relay
+ * unconditionally; stdout is only ever relayed on the two branches that
+ * immediately exit, so nothing else can write to stdout afterward.
+ */
 function tryRun(bin, runArgs) {
   try {
     const result = spawnSync(bin, runArgs, {
       cwd: projectRoot,
-      stdio: 'inherit',
+      stdio: ['inherit', 'pipe', 'pipe'],
       windowsHide: true,
       env: process.env,
+      encoding: 'utf8',
       timeout: SPAWN_TIMEOUT,
     });
     if (result.error) {
       return false;
     }
+    if (result.stderr) {
+      process.stderr.write(result.stderr);
+    }
     if (result.status === 0) {
+      if (result.stdout) process.stdout.write(result.stdout);
       process.exit(0);
     }
     if (!isAgy && result.status === 2) {
@@ -91,8 +91,13 @@ function fallback() {
 }
 
 try {
+  // spawnSync('bun', ['--version']) as a pre-check before every real attempt
+  // used to cost a second subprocess on every single hook invocation. A
+  // missing/unrunnable 'bun' already surfaces as `result.error` inside
+  // tryRun(), so the pre-check is redundant — dropping it halves the spawn
+  // count (and the worst-case latency) for the common case where bun exists.
   const srcMain = join(projectRoot, 'src', 'cli', 'main.ts');
-  if (existsSync(srcMain) && canRun('bun')) {
+  if (existsSync(srcMain)) {
     tryRun('bun', ['run', srcMain, 'hook', event, ...extra]);
   }
 
@@ -112,4 +117,3 @@ try {
 }
 
 fallback();
-

package/presets/agy/skills/android-ui-design/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: android-ui-design
+description: >-
+  Design, implement, review, and audit Android Jetpack Compose UI/UX for phone
+  interfaces. Use when a request concerns concrete Compose layout, components,
+  interaction, accessibility, or visual behavior. Do not activate for framework
+  or dependency presence alone; non-UI Android work is excluded.
+---
+
+# Android UI design
+
+Apply this specialized guidance to Android phone interfaces built with Jetpack
+Compose. Keep the active `cc-feature`, `cc-fix`, `cc-review`, or `cc-openspec`
+workflow and its gates; this skill contributes UI/UX criteria, not a separate
+workflow. Use the general `android` skill for architecture, dependency injection,
+Media3, performance, testing, and other non-UI Android engineering.
+
+## Intake and boundaries
+
+Identify the user goal, phone surface, affected interaction, supported Android
+versions, and observable outcomes. Inspect the existing Compose components,
+design tokens, navigation conventions, installed versions, tests, previews, and
+available emulator or device tooling before proposing changes.
+
+Preserve the established product visual system, including its components, color,
+type, shape, spacing, and motion tokens. Material 3 is advisory guidance, not a
+mandate to replace a deliberate product language. Suggest Material 3 changes with
+their accessibility or usability benefit and wait for scope approval when they
+would alter the visual direction.
+
+The initial scope is phones. Do not invent tablet, foldable, desktop, or wearable
+layouts. Still account for phone portrait and landscape orientation, window size
+changes, display cutouts, system bars, and the soft keyboard or IME.
+
+## Design mode
+
+Turn the request into a small interaction contract before implementation:
+
+- Define hierarchy, content, spacing, phone layout, scroll and overflow behavior,
+  navigation, focus entry and return, gestures, and predictive back behavior.
+- Specify applicable default, pressed, focused, disabled, pending or loading,
+  empty, success, error or failure, and offline states. State what changes and
+  what the user can do next; never imply success before it is known.
+- Name the state owner. Prefer state hoisting, a single source of truth, and
+  unidirectional data flow (UDF); keep transient visual state local only when no
+  external owner needs to observe or control it.
+- Design edge-to-edge intentionally with WindowInsets and system bars. Define IME
+  resize, pan, focus, dismissal, and restoration behavior for editable surfaces.
+- Require at least 48dp touch targets, meaningful semantics, TalkBack labels and
+  actions, logical traversal or focus order, sufficient contrast, and usable font
+  scaling without clipped or hidden actions.
+- Add motion only when it has a purpose such as continuity, spatial orientation,
+  feedback, or state change. Define start/end state, interruption, cancellation
+  or reversal, repeated or rapid input, and reduced-motion or reduced-animation
+  behavior that preserves essential information.
+
+Use existing components and platform/Compose primitives before adding code or a
+dependency. When alternatives are requested, compare only scoped options and make
+the product-system and Material 3 tradeoffs explicit.
+
+## Implementation mode
+
+Implement the accepted contract without expanding the visual language. Keep
+composables focused, pass immutable UI state and event callbacks, and preserve
+unidirectional data flow. Hoist state to the lowest common owner that needs to
+read or write it. Do not duplicate navigation, loading, or failure truth across
+the composition.
+
+Prefer semantic Material/Compose controls over raw pointer input. When a custom
+gesture is necessary, preserve accessible actions, minimum touch targets, visual
+feedback, cancellation, and interoperability with scrolling. Consume insets once
+at the correct boundary and verify that edge-to-edge content and IME transitions
+do not obscure controls.
+
+Write tests for observable behavior and state outcomes rather than modifier or
+implementation details. Cover the relevant state transition, duplicate or rapid
+input, disabled behavior, semantics, navigation/back behavior, and state
+restoration. Use previews as design aids, not as proof of runtime interaction.
+
+## Review mode
+
+Review the agreed surface against the interaction contract and existing Review
+Report rules. Each finding needs a location, reproduction or evidence, user
+impact, and proposed resolution. Treat contract and accessibility failures as
+defects; classify unsupported aesthetic preferences as suggestions. Do not create
+a new review axis or elevate a Material 3 preference over the product system.
+
+Check state completeness, TalkBack semantics and traversal, 48dp touch targets,
+contrast and font scaling, focus/IME behavior, edge-to-edge insets, gestures,
+predictive back, orientation changes, state ownership/UDF, motion interruption,
+reduced animation, and rapid repeated interaction as applicable.
+
+## Audit mode
+
+A requested audit is read-only. Inspect only the agreed Compose phone surface and
+report prioritized, evidence-backed findings; an audit is not permission to edit,
+implement, modify, or automatically fix the UI. Keep out-of-scope improvements as
+suggestions and create backlog work only when requested through the existing
+workflow.
+
+Distinguish code inspection, semantics tests, screenshots, and live emulator or
+device interaction because they prove different things. If required visual,
+emulator, or device evidence is unavailable, mark that validation pending with
+the surface, steps, expected result, and limitation. Do not claim visual
+validation or a completed acceptance criterion without executing the check.
+
+## Evidence and delivery
+
+Report the observable outcomes checked, commands or tools used, results, and
+limitations. A screenshot cannot prove TalkBack traversal, gesture interruption,
+IME recovery, predictive back, or repeated-input behavior. Prefer a real phone or
+phone emulator for those checks; otherwise leave precise pending verification.
+
+Primary Android references: [Compose semantics](https://developer.android.com/develop/ui/compose/accessibility/semantics),
+[accessibility defaults](https://developer.android.com/develop/ui/compose/accessibility/api-defaults),
+[state and hoisting](https://developer.android.com/develop/ui/compose/state),
+[window insets](https://developer.android.com/develop/ui/compose/system/insets),
+[predictive back](https://developer.android.com/develop/ui/compose/system/predictive-back),
+and [Compose accessibility testing](https://developer.android.com/develop/ui/compose/accessibility/testing).

package/presets/agy/skills/cc-feature/SKILL.md

@@ -9,6 +9,28 @@ description:
 
 Feature request: $ARGUMENTS
 
+## Web interface scope
+
+When the task concerns web layout, component states, feedback, motion, or a
+requested UI audit, apply skill `web-design-engineering` from the installed skill
+library. Use it during intake/discovery, design, test/implement, and review as
+applicable; keep this workflow’s gates and TDD order. Framework presence alone
+does not activate it; backend-only and native mobile work are excluded. Record
+required visual checks as pending when unavailable. Keep findings in the existing
+Review Report: contract failures in Spec Axis, technical issues in existing
+subchecks, and aesthetic preferences as suggestions; do not add an axis.
+
+## Android phone interface scope
+
+When the task concerns concrete Jetpack Compose phone layout, component states,
+interaction, accessibility, visual behavior, or a requested UI audit, apply skill
+`android-ui-design`. Use it during design, test/implementation, and review as
+applicable while keeping this workflow's gates and TDD order. Kotlin, Compose,
+framework, or dependency presence alone does not activate it; non-UI Android work
+stays with the general `android` skill. Audit-only requests remain read-only, and
+unavailable visual or emulator checks remain pending rather than claimed complete.
+
+
 ## Step 1 — Task Card validation (task-coach)
 
 Invoke `task-coach` with the feature description above.

package/presets/agy/skills/cc-fix/SKILL.md

@@ -19,6 +19,28 @@ Provide the following information in $ARGUMENTS:
 
 ---
 
+## Web interface scope
+
+When the task concerns web layout, component states, feedback, motion, or a
+requested UI audit, apply skill `web-design-engineering` from the installed skill
+library. Use it during intake/discovery, design, test/implement, and review as
+applicable; keep this workflow’s gates and TDD order. Framework presence alone
+does not activate it; backend-only and native mobile work are excluded. Record
+required visual checks as pending when unavailable. Keep findings in the existing
+Review Report: contract failures in Spec Axis, technical issues in existing
+subchecks, and aesthetic preferences as suggestions; do not add an axis.
+
+## Android phone interface scope
+
+When the task concerns concrete Jetpack Compose phone layout, component states,
+interaction, accessibility, visual behavior, or a requested UI audit, apply skill
+`android-ui-design`. Use it during design, test/implementation, and review as
+applicable while keeping this workflow's gates and TDD order. Kotlin, Compose,
+framework, or dependency presence alone does not activate it; non-UI Android work
+stays with the general `android` skill. Audit-only requests remain read-only, and
+unavailable visual or emulator checks remain pending rather than claimed complete.
+
+
 ## Step 1 — Task Card validation (task-coach)
 
 Invoke `task-coach` with the bug description above.

package/presets/agy/skills/cc-review/SKILL.md

@@ -18,6 +18,28 @@ Specify what to review. Accepted formats:
 
 ---
 
+## Web interface scope
+
+When the task concerns web layout, component states, feedback, motion, or a
+requested UI audit, apply skill `web-design-engineering` from the installed skill
+library. Use it during intake/discovery, design, test/implement, and review as
+applicable; keep this workflow’s gates and TDD order. Framework presence alone
+does not activate it; backend-only and native mobile work are excluded. Record
+required visual checks as pending when unavailable. Keep findings in the existing
+Review Report: contract failures in Spec Axis, technical issues in existing
+subchecks, and aesthetic preferences as suggestions; do not add an axis.
+
+## Android phone interface scope
+
+When the task concerns concrete Jetpack Compose phone layout, component states,
+interaction, accessibility, visual behavior, or a requested UI audit, apply skill
+`android-ui-design`. Use it during design, test/implementation, and review as
+applicable while keeping this workflow's gates and TDD order. Kotlin, Compose,
+framework, or dependency presence alone does not activate it; non-UI Android work
+stays with the general `android` skill. Audit-only requests remain read-only, and
+unavailable visual or emulator checks remain pending rather than claimed complete.
+
+
 ## Step 1 — Diff collection
 
 Before invoking `reviewer`, collect the diff for the specified target.

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

@@ -42,6 +42,26 @@ Status machine: `TODO` → `READY` → `PLANNED` → `IN_PROGRESS` → `REVIEW`
 → Archive. `BLOCKED` returns to `READY`. Reviewer rejection: `REVIEW` →
 `IN_PROGRESS`.
 
+## Web interface scope
+
+When the task concerns web layout, component states, feedback, motion, or a
+requested UI audit, apply skill `web-design-engineering` from the installed skill
+library. Use it during intake/discovery, design, test/implement, and review as
+applicable; keep this workflow’s gates and TDD order. Framework presence alone
+does not activate it; backend-only and native mobile work are excluded. Record
+required visual checks as pending when unavailable. Keep findings in the existing
+Review Report: contract failures in Spec Axis, technical issues in existing
+subchecks, and aesthetic preferences as suggestions; do not add an axis.
+
+## Android phone interface scope
+
+When an item concerns concrete Jetpack Compose phone layout, component states,
+interaction, accessibility, visual behavior, or a requested UI audit, apply skill
+`android-ui-design` throughout discover, design, test/implement, and review. Keep
+OpenSpec gates and TDD order. Kotlin, Compose, framework, or dependency presence
+alone does not activate it; non-UI Android work stays with `android`. Keep audit-only
+delivery read-only and record unavailable visual or emulator evidence as pending.
+
 ## Common Rationalizations
 
 | Rationalization | Reality |

package/presets/agy/skills/using-cc-skills/SKILL.md

@@ -31,6 +31,27 @@ a parallel process.
 Then run the matching CLI (`openspec validate`, `scorecard create --from-diff`,
 `hook pre-tool`, `scorecard suite-run`).
 
+## Web interface scope
+
+When the task concerns web layout, component states, feedback, motion, or a
+requested UI audit, apply skill `web-design-engineering` from the installed skill
+library. Use it during intake/discovery, design, test/implement, and review as
+applicable; keep this workflow’s gates and TDD order. Framework presence alone
+does not activate it; backend-only and native mobile work are excluded. Record
+required visual checks as pending when unavailable. Keep findings in the existing
+Review Report: contract failures in Spec Axis, technical issues in existing
+subchecks, and aesthetic preferences as suggestions; do not add an axis.
+
+## Android phone interface scope
+
+When the task concerns concrete Jetpack Compose phone layout, component states,
+interaction, accessibility, visual behavior, or a requested UI audit, apply skill
+`android-ui-design`. Use it during design, test/implementation, and review as
+applicable while preserving the current workflow gates. Kotlin, Compose, framework,
+or dependency presence alone does not activate it; non-UI Android work stays with
+the general `android` skill. Audit-only requests remain read-only, and unavailable
+visual or emulator checks remain pending rather than claimed as complete.
+
 ## Common Rationalizations
 
 | Rationalization | Reality |