@agentic-coding-framework/orchestrator-core 0.1.2 → 0.3.0

package/dist/rules.js

@@ -19,7 +19,7 @@ exports.getStepSequence = getStepSequence;
 /** Complexity-to-dispatch-mode mapping */
 exports.DISPATCH_MODES = {
     S: "single",
-    M: "auto", // check [P] count, enable team only if ≥ 2
+    M: "auto", // check [P] count, enable team only if >= 2
     L: "team",
 };
 // ─── Step Rules Table ────────────────────────────────────────────────────────
@@ -201,70 +201,6 @@ exports.STEP_RULES = {
             "If the task is unclear, fill reason with needs_clarification.",
     },
 };
-// ─── Custom Task Use Cases ──────────────────────────────────────────────────
-//
-// The "custom" step is a generic passthrough that lets OpenClaw forward ANY
-// instruction to Claude Code with full project context. Common use cases:
-//
-// ── Refactoring ──
-//   "Extract authentication logic into a separate auth module"
-//   "Rename all UserDTO references to UserResponse"
-//   "Convert class components to functional components with hooks"
-//   "Split monolithic service.ts into domain-specific modules"
-//
-// ── Code Review ──
-//   "Review src/api/ for security vulnerabilities"
-//   "Review PR #42 changes and list potential issues"
-//   "Check all error handling paths in the payment flow"
-//   "Audit dependencies for known CVEs"
-//
-// ── Bug Fix (hotfix, not full story) ──
-//   "Fix the race condition in WebSocket reconnection"
-//   "Debug why /api/users returns 500 on empty query"
-//   "Fix memory leak in event listener cleanup"
-//
-// ── DevOps / Infrastructure ──
-//   "Add GitHub Actions CI pipeline for lint + test + build"
-//   "Create Dockerfile and docker-compose.yml for local dev"
-//   "Set up pre-commit hooks for linting and formatting"
-//   "Configure Renovate for automated dependency updates"
-//
-// ── Documentation ──
-//   "Add JSDoc comments to all exported functions in src/api/"
-//   "Update README with current API endpoints and examples"
-//   "Generate OpenAPI spec from existing route handlers"
-//   "Write architecture decision record for database choice"
-//
-// ── Testing ──
-//   "Add unit tests for utils/validation.ts (target 90% coverage)"
-//   "Write integration tests for the checkout flow"
-//   "Add snapshot tests for all React components in src/ui/"
-//   "Set up E2E tests with Playwright for critical user paths"
-//
-// ── Dependency / Migration ──
-//   "Upgrade React from v17 to v18, fix breaking changes"
-//   "Migrate from Express to Fastify"
-//   "Replace moment.js with date-fns"
-//   "Migrate database schema: add soft delete to all entities"
-//
-// ── Performance ──
-//   "Profile and optimize the dashboard query (currently 3s)"
-//   "Add Redis caching for /api/products endpoint"
-//   "Implement virtual scrolling for the transaction list"
-//   "Lazy-load all route components with React.lazy"
-//
-// ── Security ──
-//   "Add rate limiting to all authentication endpoints"
-//   "Implement CSRF protection for form submissions"
-//   "Sanitize all user inputs in the search endpoint"
-//   "Add Content-Security-Policy headers"
-//
-// ── Cleanup ──
-//   "Remove all unused imports and dead code"
-//   "Standardize error response format across all endpoints"
-//   "Replace console.log with structured logger"
-//   "Fix all TypeScript strict mode errors"
-//
 // ─── Bootstrap Rule (special: one-time, not in the micro-waterfall loop) ─────
 exports.BOOTSTRAP_RULE = {
     display_name: "Bootstrap",
@@ -331,9 +267,22 @@ function getRule(step) {
         throw new Error('No rule for "done" — story is complete');
     return exports.STEP_RULES[step];
 }
-/** Resolve {story} placeholders in file paths */
+/**
+ * Resolve {story} placeholders in file paths.
+ *
+ * [FIX P0] Handles double-prefix prevention:
+ * Templates use "US-{story}" but storyId may already be "US-013".
+ * If template has "US-{story}" and storyId starts with "US-",
+ * replace "US-{story}" as a whole unit → "US-013" (not "US-US-013").
+ */
 function resolvePaths(paths, storyId) {
-    return paths.map((p) => p.replace(/\{story\}/g, storyId));
+    return paths.map((p) => {
+        // [FIX P0] Prevent double-prefix: "US-{story}" + "US-013" → "US-013" not "US-US-013"
+        if (p.includes("US-{story}") && storyId.startsWith("US-")) {
+            return p.replace(/US-\{story\}/g, storyId);
+        }
+        return p.replace(/\{story\}/g, storyId);
+    });
 }
 /** Determine dispatch mode from complexity marker */
 function getDispatchMode(complexity, parallelCount = 0) {
@@ -364,3 +313,4 @@ function getStepSequence() {
         "update-memory",
     ];
 }
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"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"}

package/dist/state.d.ts

@@ -4,58 +4,29 @@
  * Maps directly to the Agentic Coding Protocol's STATE.json field specifications.
  * All operations are synchronous file I/O — zero LLM tokens.
  */
-/** Micro-waterfall steps, matching Protocol's valid step values */
-export type Step = "bootstrap" | "bdd" | "sdd-delta" | "contract" | "review" | "scaffold" | "impl" | "verify" | "update-memory" | "custom" | "done";
-/** Task type determines which pipeline to follow */
-export type TaskType = "story" | "custom";
-/** STATE.json status state machine:
- *  pending → running → pass | failing | timeout | needs_human */
-export type Status = "pending" | "running" | "pass" | "failing" | "needs_human" | "timeout";
-/** Reason codes extracted from HANDOFF.md, driving reason-based routing */
-export type Reason = "constitution_violation" | "needs_clarification" | "nfr_missing" | "scope_warning" | "test_timeout";
-/** Test result summary */
-export interface TestResult {
+export interface TestResults {
     pass: number;
     fail: number;
     skip: number;
 }
-/** Complete STATE.json schema — every field from the Protocol spec */
 export interface State {
-    /** Project identifier */
     project: string;
-    /** Current User Story ID (e.g., "US-005") */
     story: string | null;
-    /** Current micro-waterfall step */
-    step: Step;
-    /** Attempt count for current step (1-indexed) */
+    step: string;
     attempt: number;
-    /** Maximum attempts allowed (from rules table) */
     max_attempts: number;
-    /** Current status */
-    status: Status;
-    /** Failure reason code (null = general failure/success) */
-    reason: Reason | null;
-    /** ISO 8601 timestamp when executor was dispatched */
+    status: string;
+    reason: string | null;
     dispatched_at: string | null;
-    /** ISO 8601 timestamp when executor completed */
     completed_at: string | null;
-    /** Timeout in minutes (from rules table) */
     timeout_min: number;
-    /** Test result summary */
-    tests: TestResult | null;
-    /** Names of failing tests */
+    tests: TestResults | null;
     failing_tests: string[];
-    /** Whether linting passed */
     lint_pass: boolean | null;
-    /** Files modified in this run */
     files_changed: string[];
-    /** Story IDs that block this story */
     blocked_by: string[];
-    /** Human instruction transcribed from communication channel */
     human_note: string | null;
-    /** Task type: "story" for micro-waterfall, "custom" for ad-hoc tasks */
-    task_type: TaskType;
-    /** Whether CC is allowed to spawn agent-teams for this task */
+    task_type: string;
     agent_teams: boolean;
 }
 /** Create a blank STATE.json for a new project */
@@ -71,6 +42,19 @@ export declare function initState(projectRoot: string, project: string): {
     created: boolean;
     state: State;
 };
+/** Path to CLAUDE.md in project root */
+export declare function claudeMdPath(projectRoot: string): string;
+/**
+ * Generate CLAUDE.md content for ACF-enabled projects.
+ * CC reads this file automatically on every session start,
+ * ensuring it follows the ACF workflow even without dispatch.
+ */
+export declare function generateClaudeMd(project: string): string;
+/**
+ * Write CLAUDE.md to project root.
+ * Returns true if created, false if already exists (no overwrite).
+ */
+export declare function writeClaudeMd(projectRoot: string, project: string, force?: boolean): boolean;
 /** Validate a State object. Throws on invalid fields. */
 export declare function validate(state: State): void;
 /** Check if a step has exceeded its timeout */
@@ -80,4 +64,5 @@ export declare function isMaxedOut(state: State): boolean;
 /** Mark state as running with dispatch timestamp */
 export declare function markRunning(state: State): State;
 /** Mark state as completed (pass or failing) with timestamp */
-export declare function markCompleted(state: State, status: "pass" | "failing" | "needs_human", reason?: Reason | null): State;
+export declare function markCompleted(state: State, status: string, reason?: string | null): State;
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,KAAK;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;CACtB;AAID,kDAAkD;AAClD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAqBzD;AAID,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK,CASpD;AAED,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAQlE;AAED,4EAA4E;AAC5E,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAQpC;AAID,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA0CxD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,KAAK,UAAQ,GACZ,OAAO,CAOT;AAmCD,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAyB3C;AAID,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAKhD;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAEhD;AAED,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAQ/C;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAC3B,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAM,GAAG,IAAW,GAC3B,KAAK,CAOP"}

package/dist/state.js

@@ -11,6 +11,9 @@ exports.statePath = statePath;
 exports.readState = readState;
 exports.writeState = writeState;
 exports.initState = initState;
+exports.claudeMdPath = claudeMdPath;
+exports.generateClaudeMd = generateClaudeMd;
+exports.writeClaudeMd = writeClaudeMd;
 exports.validate = validate;
 exports.isTimedOut = isTimedOut;
 exports.isMaxedOut = isMaxedOut;
@@ -78,6 +81,71 @@ function initState(projectRoot, project) {
     writeState(projectRoot, state);
     return { created: true, state };
 }
+// ─── CLAUDE.md Generation ─────────────────────────────────────────────────
+/** Path to CLAUDE.md in project root */
+function claudeMdPath(projectRoot) {
+    return (0, path_1.join)(projectRoot, "CLAUDE.md");
+}
+/**
+ * Generate CLAUDE.md content for ACF-enabled projects.
+ * CC reads this file automatically on every session start,
+ * ensuring it follows the ACF workflow even without dispatch.
+ */
+function generateClaudeMd(project) {
+    return `# ${project} — Agentic Coding Framework
+
+This project uses the **Agentic Coding Framework (ACF)** with an orchestrator-driven
+micro-waterfall pipeline. You MUST follow the ACF workflow — do NOT work freestyle.
+
+## How to Work in This Project
+
+1. **Check current state first:**
+   Read \`.ai/STATE.json\` to understand which step and status the project is in.
+
+2. **Follow the orchestrator — never skip steps:**
+   The pipeline is: bootstrap → bdd → sdd-delta → contract → review → scaffold → impl → verify → update-memory → done.
+   Each step has specific inputs, outputs, and acceptance criteria.
+
+3. **Use the orchestrator CLI** (preferred):
+   \`\`\`bash
+   orchestrator dispatch .       # Get your current task prompt
+   orchestrator status .         # Check pipeline status
+   \`\`\`
+
+4. **Always update .ai/HANDOFF.md when done:**
+   After completing your work, write a YAML front-matter summary to \`.ai/HANDOFF.md\`
+   with: story, step, attempt, status (pass/failing), reason, files_changed, and tests.
+   The orchestrator hook reads this to advance the pipeline.
+
+## Key Rules
+
+- **Do NOT modify .ai/STATE.json directly** — the orchestrator manages it.
+- **Do NOT skip to a different step** — always complete the current step first.
+- If requirements are unclear, set status: \`failing\` and reason: \`needs_clarification\` in HANDOFF.md.
+- If you find a Constitution violation, set reason: \`constitution_violation\`.
+- Read \`.ai/PROJECT_MEMORY.md\` for cross-session context and architectural decisions.
+
+## Files
+
+| File | Purpose | Who writes |
+|------|---------|-----------|
+| \`.ai/STATE.json\` | Pipeline state machine | Orchestrator only |
+| \`.ai/HANDOFF.md\` | Executor ↔ Orchestrator bridge | You (CC) |
+| \`.ai/PROJECT_MEMORY.md\` | Cross-session knowledge | You (at update-memory step) |
+`;
+}
+/**
+ * Write CLAUDE.md to project root.
+ * Returns true if created, false if already exists (no overwrite).
+ */
+function writeClaudeMd(projectRoot, project, force = false) {
+    const path = claudeMdPath(projectRoot);
+    if ((0, fs_1.existsSync)(path) && !force) {
+        return false;
+    }
+    (0, fs_1.writeFileSync)(path, generateClaudeMd(project), "utf-8");
+    return true;
+}
 // ─── Validation ──────────────────────────────────────────────────────────────
 const VALID_STEPS = new Set([
     "bootstrap",
@@ -159,3 +227,4 @@ function markCompleted(state, status, reason = null) {
         completed_at: new Date().toISOString(),
     };
 }
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-coding-framework/orchestrator-core",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Zero-token orchestrator for the Agentic Coding Protocol — state machine, rules table, dispatch logic, CC integration",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -17,25 +17,5 @@
   "files": [
     "dist",
     "README.md"
-  ],
-  "keywords": [
-    "agentic-coding",
-    "orchestrator",
-    "claude-code",
-    "ai-coding",
-    "state-machine",
-    "micro-waterfall"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/MaWeiChi/agentic-coding-orchestrator.git",
-    "directory": "agentic-coding-orchestrator"
-  },
-  "author": "MaWeiChi",
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.4.0",
-    "vitest": "^2.0.0"
-  }
+  ]
 }