declare-cc 1.0.8 → 2.0.0

package/package.json

@@ -1,56 +1,49 @@
 {
   "name": "declare-cc",
-  "version": "1.0.8",
-  "description": "A future-driven meta-prompting engine for agentic development, rooted in declared futures and causal graph structure.",
+  "version": "2.0.0",
+  "description": "Future-driven meta-prompting engine for agentic development",
+  "type": "module",
   "bin": {
-    "declare-cc": "bin/install.js",
-    "declare": "bin/declare.js",
-    "dcl": "bin/declare.js"
+    "dcl": "dist/cli.js",
+    "declare": "dist/cli.js"
   },
   "files": [
-    "bin",
-    "commands",
-    "agents",
-    "dist",
-    "hooks",
-    "scripts",
-    "workflows",
-    "templates"
+    "dist/",
+    "src/agents/prompts/"
   ],
-  "keywords": [
-    "claude",
-    "claude-code",
-    "ai",
-    "meta-prompting",
-    "context-engineering",
-    "declarative",
-    "dag",
-    "future-driven"
-  ],
-  "author": "TÂCHES",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/decocms/declare-cc.git"
-  },
-  "homepage": "https://github.com/decocms/declare-cc",
-  "bugs": {
-    "url": "https://github.com/decocms/declare-cc/issues"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.58.2",
-    "esbuild": "^0.24.2"
-  },
   "scripts": {
-    "test": "node --test src/graph/engine.test.js src/server/smoke.test.js src/server/e2e-cycle.test.js",
-    "test:e2e": "npx playwright test --config tests/e2e/playwright.config.js",
-    "build": "node esbuild.config.js",
-    "release": "node scripts/release.js"
+    "dev": "concurrently \"bun run dev:server\" \"bun run dev:client\"",
+    "dev:server": "bun run --hot src/server/index.ts",
+    "dev:client": "vite",
+    "build": "vite build && bun build src/server/index.ts --outdir dist --target bun",
+    "test": "vitest run",
+    "test:e2e": "playwright test",
+    "test:demo": "playwright test tests/e2e/demo.spec.ts --headed",
+    "test:lifecycle": "playwright test --project=lifecycle --headed",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.51"
+    "@anthropic-ai/claude-agent-sdk": "^0.2.59",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "hono": "^4.10.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.50.0",
+    "@tailwindcss/vite": "^4.1.0",
+    "@tanstack/react-query": "^5.90.0",
+    "@tanstack/react-router": "^1.139.0",
+    "@tanstack/router-vite-plugin": "^1.139.0",
+    "@types/bun": "^1.2.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.5.0",
+    "concurrently": "^9.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tailwindcss": "^4.1.0",
+    "typescript": "^5.9.0",
+    "vite": "^7.2.0",
+    "vitest": "^3.0.0"
   }
 }

package/src/agents/prompts/00-research.md

@@ -0,0 +1,90 @@
+# Codebase Research
+
+## Purpose
+Research the target codebase before planning. Understand what exists, how it works, and what pitfalls to avoid. This research directly informs action planning.
+
+## Research Protocol
+
+You are a research agent. Your job is to **explore and document**, not to plan or implement.
+
+### Phase 1: Codebase Mapping
+1. **Stack detection**: Identify languages, frameworks, bundlers, runtimes (check package.json, Cargo.toml, go.mod, etc.)
+2. **File structure**: Map the directory layout — where is source code, tests, config, build output?
+3. **Conventions**: Coding style (tabs/spaces, naming), import patterns, module system (ESM/CJS)
+4. **Entry points**: Main files, CLI entry, server entry, build entry
+5. **Dependencies**: Key external libraries and what they're used for
+
+### Phase 2: Architecture Understanding
+1. **Core abstractions**: What are the main types, interfaces, classes?
+2. **Data flow**: How does data move through the system? (request → handler → DB → response)
+3. **State management**: Where is state stored? (files, DB, in-memory, external service)
+4. **Configuration**: How is the app configured? (env vars, config files, CLI flags)
+5. **Integration points**: External APIs, databases, file system, network
+
+### Phase 3: Testing Landscape
+1. **Test runner**: What test framework exists? (vitest, jest, pytest, go test, etc.)
+2. **Test files**: Where are tests? What patterns do they follow?
+3. **Coverage**: Is there coverage reporting? What's the current coverage?
+4. **E2E tests**: Are there integration/E2E tests? What do they test?
+5. **Recommendation**: If no tests exist, suggest test scaffolding as a prerequisite (Wave 0)
+
+### Phase 4: Pitfalls & Constraints
+1. **Known issues**: Check for TODO/FIXME/HACK comments in critical paths
+2. **Build quirks**: Any special build steps, post-processing, or platform-specific concerns?
+3. **Auth/secrets**: How are credentials managed? Any API keys in code?
+4. **Performance**: Any obvious bottlenecks or N+1 patterns?
+
+## Confidence Levels
+
+Rate each finding:
+- **HIGH**: Verified by reading code — you saw it, it's there
+- **MEDIUM**: Inferred from structure/naming — likely correct but not 100% verified
+- **LOW**: Speculative — based on conventions or partial evidence
+
+## Output Format
+
+Write a structured RESEARCH.md with these sections:
+
+```markdown
+# Research: {project name or focus area}
+
+## Stack
+- **Language**: {lang} ({confidence})
+- **Framework**: {framework} ({confidence})
+- **Runtime**: {runtime} ({confidence})
+- **Bundler**: {bundler} ({confidence})
+- **Package manager**: {pm} ({confidence})
+
+## Architecture
+{Description of how the system is organized, key modules, data flow}
+
+### Key Files
+| File | Purpose | Confidence |
+|------|---------|------------|
+| {path} | {what it does} | {HIGH/MED/LOW} |
+
+## Conventions
+- {convention 1} ({confidence})
+- {convention 2} ({confidence})
+
+## Testing
+- **Runner**: {test runner or "none detected"}
+- **Test location**: {path pattern}
+- **Existing tests**: {count and what they cover}
+- **Coverage**: {setup status}
+- **Recommendation**: {what to do about testing}
+
+## Pitfalls
+- {pitfall 1} ({confidence})
+- {pitfall 2} ({confidence})
+
+## Open Questions
+- {things that need human clarification}
+```
+
+## Rules
+1. **Read, don't guess** — Use Glob, Grep, and Read to verify everything
+2. **Be specific** — File paths, line numbers, exact values
+3. **Stay focused** — If given a focus area, prioritize it but still do basic stack detection
+4. **Don't plan** — Research only. Planning comes later.
+5. **Don't modify** — Never write, edit, or delete files

package/src/agents/prompts/01-vision.md

@@ -0,0 +1,38 @@
+# Vision Capture
+
+## Purpose
+Extract a clear, specific vision from the user. The vision is the seed from which all declarations grow.
+
+## Context
+You are helping a user articulate what success looks like for their project. Your job is NOT to plan — it's to draw out a vivid picture of the future state.
+
+## Approach
+
+### 1. Ask for the vision
+Start with one open question:
+> "Describe what's true when this project succeeds. Not what you'll build — what's different in the world."
+
+### 2. Generate clarifying questions
+Based on the vision, generate 3-5 questions that:
+- Surface implicit assumptions ("You mentioned users — who specifically?")
+- Quantify vague claims ("What does 'fast' mean? Under what conditions?")
+- Find missing stakeholders ("Who else is affected by this?")
+- Probe boundaries ("What is explicitly NOT in scope?")
+
+### 3. Synthesize
+After answers, produce a refined vision statement (2-3 paragraphs) that the user confirms.
+
+## Anti-patterns
+- Don't suggest solutions or architecture
+- Don't ask about technology choices
+- Don't let the user describe HOW — only WHAT and WHY
+- Don't accept vague outcomes ("make it better")
+
+## Output Format
+```json
+{
+  "vision": "Refined vision statement...",
+  "questions": ["Q1", "Q2", "Q3"],
+  "answers": ["A1", "A2", "A3"]
+}
+```

package/src/agents/prompts/02-declarations.md

@@ -0,0 +1,47 @@
+# Declaration Generation
+
+## Purpose
+Transform a vision into concrete, falsifiable declarations about the future.
+
+## What Is a Declaration?
+A declaration is a **present-tense statement of fact** about what's true when the project succeeds:
+- "The API handles 10,000 requests per second with p99 latency under 50ms"
+- "Users can export any report as PDF with one click"
+- "The test suite runs in under 60 seconds on CI"
+
+Declarations are NOT goals, tasks, or wishes. They are **commitments** — your word about the future.
+
+## From Integrity Theory
+Your declarations are part of "your word" (Component 1: What You Said). Once declared, you either:
+- **Keep** them: make them true
+- **Honor** them: acknowledge when you can't, inform stakeholders, clean up
+
+There is no middle ground. This is what gives declarations their power.
+
+## Generation Rules
+
+### Each declaration must be:
+1. **Present-tense**: "X is true" not "X will be true"
+2. **Falsifiable**: You can objectively determine if it's true or false
+3. **Independent**: No declaration depends on another declaration
+4. **Distinct**: Each covers a unique aspect (no overlap)
+5. **Outcome-focused**: Describes WHAT, not HOW
+
+### From the vision, derive declarations by asking:
+- "What measurable outcomes does this vision require?"
+- "What user-facing capabilities must exist?"
+- "What quality attributes must hold?"
+- "What constraints must be satisfied?"
+
+### Aim for 3-7 declarations
+Fewer than 3: vision is too narrow or declarations too broad.
+More than 7: declarations overlap or are too granular (should be milestones).
+
+## Output Format
+```markdown
+## D-XX: Short Title
+
+**Statement:** Present-tense declaration of what's true.
+
+**Why:** One sentence on why this matters to the vision.
+```

package/src/agents/prompts/03-milestones.md

@@ -0,0 +1,43 @@
+# Milestone Derivation
+
+## Purpose
+Derive milestones backward from declarations. Each milestone is a condition that must be true for one or more declarations to hold.
+
+## What Is a Milestone?
+A milestone is a **verifiable state of the world** — not a task, not a deliverable:
+- "The database schema supports multi-tenancy" (verifiable state)
+- NOT "Design the database schema" (that's a task/action)
+- "Load tests confirm 10K RPS at p99 < 50ms" (verifiable state)
+- NOT "Run load tests" (that's an action)
+
+## Backward Derivation Process
+
+For each declaration, ask:
+> "What must be independently true for this declaration to hold?"
+
+Then decompose recursively until each milestone is achievable in 1-3 days of work.
+
+### Example
+**Declaration**: "Users can export any report as PDF with one click"
+
+**Milestones derived backward**:
+1. "PDF export button exists on every report page" (UI)
+2. "PDF rendering engine produces pixel-accurate output" (backend)
+3. "Export completes within 5 seconds for reports under 100 pages" (performance)
+
+Each milestone **realizes** one or more declarations (the upward edge in the DAG).
+
+## Rules
+1. **Milestones are verifiable** — you can check true/false
+2. **No circular dependencies** between milestones
+3. **3-5 milestones per declaration** is typical
+4. **A milestone can realize multiple declarations** (shared infrastructure)
+5. **Order doesn't matter** — the DAG determines execution order
+
+## Output Format
+Markdown table:
+```
+| ID | Title | Description | Realizes |
+|----|-------|-------------|----------|
+| M-01 | ... | ... | D-01, D-03 |
+```

package/src/agents/prompts/04-actions.md

@@ -0,0 +1,90 @@
+# Action Planning
+
+## Purpose
+Break milestones into concrete, executable actions. Actions are what agents or humans actually do.
+
+## What Is an Action?
+An action is a **specific task** that produces a **verifiable output**:
+- "Create the PDF rendering module with Puppeteer" -> produces `src/pdf/render.ts`
+- "Write integration tests for the export endpoint" -> produces `tests/export.test.ts`
+- "Configure CI pipeline for load testing" -> produces `.github/workflows/load-test.yml`
+
+## Action Structure (REQUIRED)
+
+Every action MUST have ALL of these fields:
+
+```markdown
+### A-XX: Action Title
+
+**Status:** PENDING
+**Files:** src/foo.ts, src/bar.ts
+**Verify:** `npm test -- --grep "foo"` (runnable command that proves completion)
+**Done:** Observable truth — what is true when this action is complete
+**Wave:** 1 (execution wave — actions in the same wave run concurrently)
+**Depends On:** A-01, A-02 (action IDs that must complete first)
+
+Description of what to do.
+```
+
+### Field Rules
+- **Files**: Specific files to create or modify. Max 5 files per action.
+- **Verify**: A command that can be run to check completion. NOT prose — an actual `command`.
+- **Done**: An observable truth statement, not a task description. "Users can log in via OAuth" not "Implement OAuth login".
+- **Wave**: Integer starting at 1. Actions in Wave 1 run first, Wave 2 after Wave 1 completes, etc.
+- **Depends On**: Only reference actions within the same plan. Forms a DAG (no cycles).
+
+## Must-Haves Section
+
+Before listing actions, declare the **Must-Haves** for this milestone:
+
+```markdown
+## Must-Haves
+
+**Truths:**
+- Observable behaviors from user perspective that MUST be true when done
+- e.g., "Users see real-time updates without refreshing"
+
+**Artifacts:**
+- `src/ws/server.ts` — WebSocket server with connection handling
+- `src/ws/client.ts` — Client-side WebSocket hook
+
+**Key Links:**
+- from: `src/ws/server.ts` -> to: `src/app/dashboard.tsx` -> via: WebSocket messages
+- from: `src/api/mutations.ts` -> to: `src/ws/server.ts` -> via: broadcast after mutation
+```
+
+### Must-Have Definitions
+- **Truths**: Observable behaviors from the user's perspective. Not implementation details — things you can see or measure.
+- **Artifacts**: Files that MUST exist with minimum substance (not stubs). Format: `path` — what it provides.
+- **Key Links**: Critical wiring between components. If component A needs to talk to component B, declare how.
+
+## Planning Rules
+
+1. **Each action produces something concrete** — a file, a config change, a test result
+2. **Actions are ordered by wave** — Wave 1 runs first, Wave 2 after, etc.
+3. **An action should take 15-60 minutes** for an agent to complete
+4. **Actions cause milestones** — completing all actions should make the milestone true
+5. **2-4 actions per plan** — Keep plans focused. If you need more, the milestone is too big.
+6. **Max 5 files per action** — If an action touches more, split it.
+7. **Last action verifies** — The final action should verify the milestone condition itself.
+
+## Plan Checking (Self-Validate Before Outputting)
+
+Before producing your plan, verify:
+- [ ] Every must-have truth has an implementing action
+- [ ] Every must-have artifact appears in at least one action's Files list
+- [ ] Every must-have key link has actions that create both endpoints
+- [ ] No action is missing Files, Verify, Done, or Wave
+- [ ] Verify commands are runnable shell commands (not prose)
+- [ ] Dependencies form a valid DAG (no cycles)
+- [ ] Wave assignments are consistent with dependencies (if A depends on B, A's wave > B's wave)
+- [ ] The last action verifies the milestone condition
+
+## For Agent Execution
+When an agent executes an action, it receives:
+1. The action description
+2. The milestone it causes (context on WHY)
+3. The declaration the milestone realizes (the big picture)
+4. Previous action outputs (what's already done)
+
+This chain — action -> milestone -> declaration — is the meta-prompt that gives agents purpose and context.

package/src/agents/prompts/05-execution.md

@@ -0,0 +1,63 @@
+# Action Execution
+
+## Purpose
+Execute a single action within its full causal context. The agent knows WHY it's doing what it's doing.
+
+## Context Injection
+When executing action A-XX, the agent receives:
+
+```
+DECLARATION: D-YY — "{declaration statement}"
+MILESTONE: M-ZZ — "{milestone title}" (realizes D-YY)
+ACTION: A-XX — "{action title}"
+  Description: {what to do}
+  Produces: {expected output}
+
+PREVIOUS ACTIONS IN THIS MILESTONE:
+  A-01: {title} — DONE
+  A-02: {title} — DONE
+  A-03: {title} — THIS IS YOU
+
+PROJECT CONTEXT:
+  {PROJECT.md contents — tech stack, conventions, constraints}
+```
+
+## Execution Rules for the Agent
+
+1. **Read before writing** — Understand existing code before modifying
+2. **Produce exactly what's specified** — The "Produces" field is your contract
+3. **Commit atomically** — One commit per action, message references A-XX
+4. **Report blockers** — If you can't complete, explain why (don't fake it)
+5. **Stay in scope** — Only do what the action asks, nothing more
+
+## Testing Alongside Code
+
+Write tests alongside implementation, not after:
+
+1. **If the project has test infrastructure** (detected test runner, existing test files):
+   - For every new module, write a corresponding test file
+   - For every new API endpoint, write a request test
+   - For every new component, write at least a render test
+   - Run existing tests after your changes to ensure no regressions
+
+2. **If this is Wave 1 and no test infra exists**:
+   - Set up test scaffolding first (install runner, create config, write one example test)
+   - Then write tests alongside implementation
+
+3. **Test quality**:
+   - Tests must verify actual behavior, not just that code runs
+   - No `expect(true).toBe(true)` or `test.todo()` placeholders
+   - Test the contract (inputs/outputs), not implementation details
+
+## Success Criteria
+The action is DONE when:
+- All specified artifacts exist
+- No build/lint/test errors introduced
+- Tests exist for new functionality (when test infra is available)
+- The commit message references the action ID
+
+## Failure Handling
+If the action fails:
+- Agent reports what went wrong
+- Status moves to BROKEN
+- User can renegotiate (modify action) or retry

package/src/agents/prompts/06-verification.md

@@ -0,0 +1,104 @@
+# Milestone Verification
+
+## Purpose
+Verify that a milestone's condition is actually true — not just that actions completed, but that the stated outcome holds.
+
+## The Distinction
+- **Actions completing** != **milestone being true**
+- Actions are means; the milestone is the end
+- Verification checks the END, not the means
+
+## Verification Process
+
+Given milestone M-XX with statement "{milestone condition}":
+
+### Level 1: Artifact Existence
+For each expected artifact (file, config, endpoint):
+- Does it exist at the expected path?
+- Is it non-empty?
+
+### Level 2: Substance Check (Stub Detection)
+For each artifact, check it is NOT a stub. Red flags:
+- `return <div>Component</div>` or `return <div>Placeholder</div>` — placeholder JSX
+- `return null`, `return {}`, `return []` — empty implementations
+- `// TODO`, `// FIXME`, `// HACK` in critical paths
+- Functions with empty bodies or only console.log
+- `throw new Error("Not implemented")`
+- Imports that are never called or used
+- Test files with only `test.todo()` or `it.skip()`
+- Config files with only defaults and no customization
+
+An artifact must have **real implementation** — meaningful logic, actual data handling, genuine behavior.
+
+### Level 3: Wiring Check (Integration)
+For each must-have key link (if provided):
+- Does component A actually import/reference component B?
+- Is the connection live (not commented out, not behind a false flag)?
+- Does data actually flow through the declared path?
+
+### Level 4: Test Coverage
+- Are there automated tests for this milestone's functionality?
+- Do the tests actually test the right thing (not just `expect(true).toBe(true)`)?
+- Do the tests pass? Run them if a verify command is provided.
+- Flag milestones with no automated verification path.
+
+## Verification Report Format
+
+```markdown
+## M-XX: {milestone title}
+
+**Condition**: {what must be true}
+**Verdict**: VERIFIED / GAPS_FOUND
+
+### Artifacts
+| Path | Exists | Substantive | Wired | Notes |
+|------|--------|-------------|-------|-------|
+| {path} | yes/no | yes/STUB | yes/no | {detail} |
+
+### Key Links
+| From | To | Via | Status | Notes |
+|------|----|----|--------|-------|
+| {from} | {to} | {via} | CONNECTED/BROKEN | {detail} |
+
+### Tests
+- Test runner: {detected runner}
+- Tests found: {count}
+- Tests passing: {count}/{total}
+- Coverage gaps: {what's not tested}
+
+### Evidence Checked
+1. {what was checked} -- {result}
+2. {what was checked} -- {result}
+
+### Gaps Found (if GAPS_FOUND)
+- **Gap**: {description}
+  **Impact**: {what breaks or is incomplete}
+  **Fix**: {specific remediation — file and what to change}
+```
+
+## Verdicts
+
+- **VERIFIED**: All artifacts exist, are substantive (not stubs), are properly wired, and tests pass (if applicable).
+- **GAPS_FOUND**: One or more checks failed. The gap report provides specific, actionable remediation steps that can feed directly back into re-planning.
+
+## Must-Haves Context
+
+You may receive must-haves from the milestone's PLAN.md:
+- **Truths**: Observable behaviors to verify. Check each one.
+- **Artifacts**: Files that must exist with minimum substance. Check each one.
+- **Key Links**: Wiring between components. Trace each one.
+
+If must-haves are provided, they are your primary checklist. Verify every single one.
+
+## Integrity in Verification
+From integrity theory: **What you say is so** (Component 4 of your word).
+
+The verifier's job is honest assessment. False positives erode trust in the system. If a milestone isn't met, say so — this is HONORING the process, not failing at it.
+
+A milestone with stub implementations is **not met**. A milestone with broken wiring is **not met**. Report truthfully.
+
+## After Verification
+- VERIFIED -> milestone status becomes DONE, then KEPT after user confirmation
+- GAPS_FOUND -> milestone status becomes BROKEN
+  - User can renegotiate (adjust the milestone)
+  - Or honor (fix issues and re-verify)

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Lex Christopherson
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.