cclaw-cli 0.1.1 → 0.2.1

package/dist/content/templates.js

@@ -4,86 +4,130 @@ export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `# Brainstorm Artifact
 
 ## Problem Statement
-- 
-
-## Clarifying Questions
-- 
-
-## Approaches (2-3)
-- Approach A:
-- Approach B:
-- Approach C:
-
-## Chosen Direction
-- 
-
-## Approval
-- Approved by:
-- Date:
+- User problem:
+- Success signal:
+- Constraints:
+
+## Alternatives Table
+| Option | Summary | Trade-offs | Recommendation |
+|---|---|---|---|
+| A |  |  |  |
+| B |  |  |  |
+| C |  |  |  |
+
+## Approved Direction
+- Selected option:
+- Why selected:
+- Approval marker:
+
+## Open Questions
+- None
 `,
     "02-scope.md": `# Scope Artifact
 
+## Prime Directives
+- Zero silent failures:
+- Every error has a name:
+- Four paths per data flow:
+
+## Premise Challenge
+- Is this the right problem?
+- Why this path?
+- What if we do nothing?
+
 ## Scope Mode
 - [ ] expand
 - [ ] selective
 - [ ] hold
 - [ ] reduce
 
-## In Scope
-- 
+## In Scope / Out of Scope
 
-## Out of Scope
+### In Scope
 - 
 
-## Strategic Risks
+### Out of Scope
 - 
 
-## Scope Contract
-- Decision owner:
-- Decision date:
+## Deferred Items
+| Item | Rationale |
+|---|---|
+|  |  |
+
+## Error & Rescue Registry
+| Capability | Failure mode | Detection | Fallback |
+|---|---|---|---|
+|  |  |  |  |
+
+## Scope Summary
+- Selected mode:
+- Accepted scope:
+- Deferred:
+- Explicitly excluded:
 `,
     "03-design.md": `# Design Artifact
 
-## Architecture
-- 
+## Architecture Boundaries
+| Component | Responsibility | Owner |
+|---|---|---|
+|  |  |  |
 
 ## Data Flow
-- 
-
-## State Transitions
-- 
+- Happy path:
+- Nil/empty input path:
+- Upstream error path:
+- Timeout/downstream path:
 
-## Failure Modes and Mitigation
-- 
+## Failure Mode Table
+| Failure mode | Trigger | Detection | Mitigation | User impact |
+|---|---|---|---|---|
+|  |  |  |  |  |
 
 ## Test Strategy
 - Unit:
 - Integration:
 - E2E:
 
-## Performance Budget
+## NOT in scope
 - 
+
+## Parallelization Strategy
+- Parallel lanes:
+- Conflict risks:
+
+## Unresolved Decisions
+| Decision | Missing info | Owner | Default |
+|---|---|---|---|
+|  |  |  |  |
 `,
     "04-spec.md": `# Specification Artifact
 
 ## Acceptance Criteria
-- 
+| ID | Criterion (observable/measurable/falsifiable) |
+|---|---|
+| AC-1 |  |
 
-## Constraints
-- 
+## Edge Cases
+| Criterion ID | Boundary case | Error case |
+|---|---|---|
+| AC-1 |  |  |
 
-## Assumptions
-- 
+## Constraints and Assumptions
+- Constraints:
+- Assumptions:
 
-## Edge Cases
-- 
+## Testability Map
+| Criterion ID | Verification approach | Command/manual steps |
+|---|---|---|
+| AC-1 |  |  |
 
-## Testability Notes
-- 
+## Approval
+- Approved by:
+- Date:
 `,
     "05-plan.md": `# Plan Artifact
 
-## Task Graph
+## Dependency Graph
 - 
 
 ## Dependency Waves
@@ -104,51 +148,80 @@ export const ARTIFACT_TEMPLATES = {
 
 Execution rule: complete and verify each wave before starting the next wave.
 
-## Ordered Tasks
-1. 
-2. 
+## Task List
+| Task ID | Description | Acceptance criterion | Verification command |
+|---|---|---|---|
+| T-1 |  |  |  |
 
 ## Acceptance Mapping
-- Task 1 -> Criteria:
-
-## Checkpoints
-- 
+| Criterion ID | Task IDs |
+|---|---|
+| AC-1 | T-1 |
 
-## User Confirmation
+## WAIT_FOR_CONFIRM
 - Status: pending
 - Confirmed by:
 `,
     "06-tdd.md": `# TDD Artifact
 
 ## RED Evidence
-- Test:
-- Failure output:
+| Slice | Test name | Command | Failure output summary |
+|---|---|---|---|
+| S-1 |  |  |  |
 
-## GREEN Result
-- Passing suite summary:
+## Acceptance Mapping
+| Slice | Plan task ID | Spec criterion ID |
+|---|---|---|
+| S-1 | T-1 | AC-1 |
+
+## Failure Analysis
+| Slice | Expected missing behavior | Actual failure reason |
+|---|---|---|
+| S-1 |  |  |
+
+## GREEN Evidence
+- Full suite command:
+- Full suite result:
 
 ## REFACTOR Notes
-- 
+- What changed:
+- Why:
+- Behavior preserved:
+
+## Traceability
+- Plan task IDs:
+- Spec criterion IDs:
 `,
     "07-review.md": `# Review Artifact
 
-## Spec Compliance
-- Status:
-- Findings:
+## Layer 1 Verdict
+| Criterion | Verdict | Evidence |
+|---|---|---|
+| AC-1 | PASS/FAIL |  |
 
-## Code Quality
-- Status:
-- Security:
-- Performance:
-- Maintainability:
+## Layer 2 Findings
+| ID | Severity | Category | Description | Status |
+|---|---|---|---|---|
+| R-1 | Critical/Important/Suggestion | correctness/security/performance/architecture |  | open/resolved |
 
-## Severity Log
+## Review Army Contract
+- See \`07-review-army.json\`
+- Reconciliation summary:
+
+## Review Readiness Dashboard
+- Layer 1 complete:
+- Layer 2 complete:
+- Review army schema valid:
+- Open critical blockers:
+- Ship recommendation:
+
+## Severity Summary
 - Critical:
 - Important:
-- Minor:
+- Suggestion:
 
-## Ready to Ship
-- yes/no
+## Final Verdict
+- APPROVED | APPROVED_WITH_CONCERNS | BLOCKED
 `,
     "07-review-army.json": `{
   "version": 1,
@@ -185,22 +258,35 @@ Execution rule: complete and verify each wave before starting the next wave.
 `,
     "08-ship.md": `# Ship Artifact
 
-## Pre-Ship Checks
-- Review pass:
-- Tests pass:
+## Preflight Results
+- Review verdict:
+- Build:
+- Tests:
+- Lint:
+- Type-check:
+- Working tree clean:
 
 ## Release Notes
-- 
+-
 
 ## Rollback Plan
 - Trigger conditions:
 - Rollback steps:
-
-## Branch Finalization
-- [ ] merge
-- [ ] pull request
-- [ ] keep branch
-- [ ] discard branch
+- Verification steps:
+
+## Monitoring
+- Metrics/logs to watch:
+- Risk note (if no monitoring):
+
+## Finalization
+- Selected enum (exactly one):
+  - FINALIZE_MERGE_LOCAL
+  - FINALIZE_OPEN_PR
+  - FINALIZE_KEEP_BRANCH
+  - FINALIZE_DISCARD_BRANCH
+- Selected label (A/B/C/D):
+- Execution result:
+- PR URL / merge commit / kept branch / discard confirmation:
 `
 };
 export const RULEBOOK_MARKDOWN = `# Cclaw Rulebook
@@ -236,6 +322,25 @@ delegate to a specialized agent or skill if the harness supports it. The primary
 2. Provide focused context (relevant files, the specific concern)
 3. Evaluate the specialist output before acting on it — do not blindly apply recommendations
 `;
+export const CURSOR_WORKFLOW_RULE_MDC = `---
+description: cclaw workflow guardrails for Cursor agent sessions
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+<!-- cclaw-managed-cursor-workflow-rule -->
+
+# Cclaw Workflow Guardrails
+
+- Follow stage order: brainstorm -> scope -> design -> spec -> plan -> test -> build -> review -> ship.
+- Read \`.cclaw/state/flow-state.json\` before acting; continue from current stage when active.
+- Use \`/cc-next\` only after required gates pass; never bypass explicit pause/approval rules.
+- Keep evidence in \`.cclaw/artifacts/\` and canonical run copies in \`.cclaw/runs/<activeRunId>/artifacts/\`.
+- For machine-only checks in design/plan/test/build/review/ship, dispatch required specialists automatically when tooling supports it.
+- Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).
+- Treat \`.cclaw/skills/using-cclaw/SKILL.md\` as routing source of truth; load contextual utility skills only when their triggers apply.
+`;
 export function buildRulesJson() {
     return {
         version: 1,

package/dist/content/utility-skills.d.ts

@@ -8,5 +8,9 @@ export declare function debuggingSkill(): string;
 export declare function performanceSkill(): string;
 export declare function ciCdSkill(): string;
 export declare function docsSkill(): string;
-export declare const UTILITY_SKILL_FOLDERS: readonly ["security", "debugging", "performance", "ci-cd", "docs"];
+export declare function executingPlansSkill(): string;
+export declare function contextEngineeringSkill(): string;
+export declare function sourceDrivenDevelopmentSkill(): string;
+export declare function frontendAccessibilitySkill(): string;
+export declare const UTILITY_SKILL_FOLDERS: readonly ["security", "debugging", "performance", "ci-cd", "docs", "executing-plans", "context-engineering", "source-driven-development", "frontend-accessibility"];
 export declare const UTILITY_SKILL_MAP: Record<string, () => string>;

package/dist/content/utility-skills.js

@@ -170,6 +170,26 @@ Build fails
 └── OOM / timeout? → Check input size, increase limits
 \`\`\`
 
+## Testing-Specific Anti-Patterns
+
+When debugging test failures, treat these as root-cause signals, not noise:
+
+- **Blind snapshot updates** (\`-u\`/accept-all) without verifying intent. This hides regressions.
+- **Mocking internals instead of boundaries** (private functions, implementation details) which creates brittle tests.
+- **Time-based sleeps** (\`setTimeout\`, arbitrary waits) instead of deterministic synchronization (\`await\` actual signal/event).
+- **Shared mutable fixtures** reused across tests, causing order-dependent failures.
+- **Unseeded randomness** in tests without fixed seeds or deterministic fixtures.
+- **Leaking global state** (env vars, fake timers, singleton caches) between tests without teardown.
+- **Disabling flaky tests** rather than isolating and fixing the non-determinism.
+
+### CI-only failure checklist
+
+If a test fails only in CI:
+1. Compare runtime versions (Node/Java/Python), OS, and locale/timezone.
+2. Check parallelism differences (worker count, test sharding, race conditions).
+3. Check filesystem/network assumptions (case sensitivity, permissions, ephemeral ports).
+4. Re-run locally with CI-like env vars and concurrency settings before changing production code.
+
 ## Anti-Patterns
 
 - Fixing the symptom (adding a null check) instead of the root cause (why is it null?)
@@ -451,17 +471,203 @@ For public APIs:
 - Documenting internal implementation details of public APIs
 `;
 }
+export function executingPlansSkill() {
+    return `---
+name: executing-plans
+description: "Execute approved plans with disciplined batching, explicit checkpoints, and gate-safe progress tracking."
+---
+
+# Executing Plans
+
+## Quick Start
+
+> 1. Confirm the plan and stage gates are approved before execution.
+> 2. Execute in batches (waves), not as one giant untracked stream.
+> 3. Stop at checkpoint boundaries for verification and user visibility.
+
+## HARD-GATE
+
+Do not start implementation execution without an approved plan artifact and explicit gate satisfaction for the current stage.
+
+## Execution Protocol
+
+1. **Load plan source of truth** from \`.cclaw/artifacts/05-plan.md\` (canonical run copy when available).
+2. **Group tasks into waves** by dependency order and risk.
+3. **Run one wave at a time** with evidence after each task (tests, build, lint, or review evidence as applicable).
+4. **Checkpoint each wave** by updating stage artifact evidence and unresolved blockers.
+5. **Stop immediately** on any hard blocker, failing gate, or unresolved critical finding.
+
+## Wave Checklist
+
+- Wave scope is explicit (task IDs + expected outputs).
+- Verification command for each task is predetermined.
+- Machine-only checks are delegated to subagents when supported.
+- User approvals are requested only at required gate boundaries.
+
+## Anti-Patterns
+
+- Executing all tasks in one pass without intermediate verification.
+- Marking tasks done without command evidence.
+- Reordering critical dependencies for speed.
+- Continuing after a gate failure hoping later tasks fix it.
+`;
+}
+export function contextEngineeringSkill() {
+    return `---
+name: context-engineering
+description: "Manage context modes and payload hygiene to keep agent execution reliable across long sessions."
+---
+
+# Context Engineering
+
+## Quick Start
+
+> 1. Read current mode from \`.cclaw/state/context-mode.json\`.
+> 2. Load only the context needed for the current stage/task.
+> 3. Switch modes intentionally when work type changes.
+
+## HARD-GATE
+
+Do not keep stale or oversized context loaded when task intent changes. Context must match current stage purpose.
+
+## Context Modes
+
+Modes are stored in \`.cclaw/contexts/\`:
+- \`default\` — balanced execution
+- \`execution\` — fast plan/test/build throughput
+- \`review\` — defect/risk discovery
+- \`incident\` — stabilization and recovery
+
+## Mode Switching Protocol
+
+1. Determine target mode based on current objective.
+2. Update \`.cclaw/state/context-mode.json\`:
+   - \`activeMode\`: target mode id
+   - \`updatedAt\`: current ISO timestamp
+3. Announce mode change in-session with one-line reason.
+4. Continue using the corresponding \`.cclaw/contexts/<mode>.md\` guidance.
+
+## Payload Hygiene Rules
+
+- Prefer stage artifacts + current diff over full-repo dumps.
+- Reference exact files/symbols, not broad vague prompts.
+- For subagents, pass self-contained instructions and expected output schema.
+- Trim or rotate outdated context after each major checkpoint.
+
+## Anti-Patterns
+
+- Staying in execution mode while doing deep review triage.
+- Switching mode without updating state.
+- Shipping decisions based on stale pre-compaction context.
+`;
+}
+export function sourceDrivenDevelopmentSkill() {
+    return `---
+name: source-driven-development
+description: "Drive implementation decisions from existing source patterns before introducing new abstractions."
+---
+
+# Source-Driven Development
+
+## Quick Start
+
+> 1. Search the repo for existing patterns before writing new code.
+> 2. Reuse proven modules/contracts unless a clear incompatibility is documented.
+> 3. Record deviations with rationale when creating net-new patterns.
+
+## HARD-GATE
+
+Do not introduce new architecture patterns or helper layers without first checking whether an equivalent source pattern already exists.
+
+## Protocol
+
+1. **Discover**: inspect related modules, adapters, tests, and conventions.
+2. **Compare**: list at least two in-repo pattern candidates.
+3. **Select**: choose reuse/extension/new with explicit rationale.
+4. **Implement**: follow selected pattern consistently across touched files.
+5. **Verify**: ensure tests and docs reflect the adopted pattern.
+
+## Selection Heuristics
+
+- Prefer extension over duplication.
+- Prefer explicit local adaptation over global abstraction when scope is narrow.
+- Prefer tested, production-used patterns over speculative design.
+
+## Required Evidence
+
+- Paths of source references reused.
+- Rationale for any intentional divergence.
+- Tests proving behavior compatibility.
+
+## Anti-Patterns
+
+- Creating “better” abstractions without source comparison.
+- Duplicating utility logic under a new name.
+- Mixing incompatible patterns in the same change set.
+`;
+}
+export function frontendAccessibilitySkill() {
+    return `---
+name: frontend-accessibility
+description: "Frontend quality lens for usability and accessibility (WCAG-oriented) during implementation and review."
+---
+
+# Frontend Accessibility
+
+## Quick Start
+
+> 1. Validate keyboard navigation and focus order first.
+> 2. Confirm semantic roles/labels and screen-reader announcements.
+> 3. Check contrast, motion, and responsive behavior before ship.
+
+## HARD-GATE
+
+Do not approve user-facing UI changes that break basic keyboard navigation or remove accessible name/role/value semantics.
+
+## Checklist
+
+1. Interactive elements are reachable and usable via keyboard only.
+2. Focus indicators are visible and logical after navigation and dialogs.
+3. Form fields have labels, error messages, and instructions tied programmatically.
+4. Color contrast meets WCAG AA expectations for text and controls.
+5. Dynamic updates (toasts/modals/async states) are announced accessibly.
+6. Motion/animation respects reduced-motion preferences where relevant.
+7. Mobile and narrow layouts preserve readability and interaction targets.
+
+## Output Format
+
+- **Issue**: concise defect description
+- **Impact**: affected users and severity
+- **Evidence**: file/component path and failing behavior
+- **Fix**: concrete remediation guidance
+
+## Anti-Patterns
+
+- Relying on placeholder text as the only form label.
+- Click-only interactions without keyboard fallback.
+- Hiding focus ring without accessible replacement.
+- Color-only status indicators with no text/aria support.
+`;
+}
 export const UTILITY_SKILL_FOLDERS = [
     "security",
     "debugging",
     "performance",
     "ci-cd",
-    "docs"
+    "docs",
+    "executing-plans",
+    "context-engineering",
+    "source-driven-development",
+    "frontend-accessibility"
 ];
 export const UTILITY_SKILL_MAP = {
     security: securityReviewSkill,
     debugging: debuggingSkill,
     performance: performanceSkill,
     "ci-cd": ciCdSkill,
-    docs: docsSkill
+    docs: docsSkill,
+    "executing-plans": executingPlansSkill,
+    "context-engineering": contextEngineeringSkill,
+    "source-driven-development": sourceDrivenDevelopmentSkill,
+    "frontend-accessibility": frontendAccessibilitySkill
 };

package/dist/delegation.d.ts

@@ -0,0 +1,21 @@
+import type { FlowStage } from "./types.js";
+export type DelegationEntry = {
+    stage: string;
+    agent: string;
+    mode: "mandatory" | "proactive";
+    status: "scheduled" | "completed" | "failed" | "waived";
+    taskId?: string;
+    waiverReason?: string;
+    ts: string;
+};
+export type DelegationLedger = {
+    runId: string;
+    entries: DelegationEntry[];
+};
+export declare function readDelegationLedger(projectRoot: string): Promise<DelegationLedger>;
+export declare function appendDelegation(projectRoot: string, entry: DelegationEntry): Promise<void>;
+export declare function checkMandatoryDelegations(projectRoot: string, stage: FlowStage): Promise<{
+    satisfied: boolean;
+    missing: string[];
+    waived: string[];
+}>;