groundswell 0.0.2 → 1.0.0

package/dist/utils/session-serialization.js

@@ -0,0 +1,217 @@
+/**
+ * Session serialization utilities
+ *
+ * @module
+ * @remarks
+ * Provides safe serialization/deserialization of SessionState objects
+ * containing SDK message types with circular reference handling.
+ *
+ * Handles edge cases including:
+ * - Circular references from application code
+ * - Non-serializable values (functions, Symbols)
+ * - Unknown type fields in SDK messages
+ * - Type validation during deserialization
+ *
+ * @example
+ * ```ts
+ * import { serializeSession, deserializeSession } from 'groundswell';
+ *
+ * const state: SessionState = { history: [], lastResult: null };
+ * const json = serializeSession(state);
+ * const restored = deserializeSession(json);
+ * console.log(restored); // { history: [], lastResult: null }
+ * ```
+ */
+/**
+ * Error thrown when session serialization fails
+ *
+ * @remarks
+ * Provides detailed error context for debugging serialization issues.
+ * Includes the property path and value that caused the failure.
+ *
+ * @public
+ */
+export class SessionSerializationError extends Error {
+    path;
+    value;
+    /**
+     * Creates a new SessionSerializationError
+     *
+     * @param message - Human-readable error message
+     * @param path - Property path where the error occurred (e.g., "history.0.tool_use_result")
+     * @param value - The value that caused the serialization failure
+     */
+    constructor(message, path, value) {
+        super(message);
+        this.path = path;
+        this.value = value;
+        this.name = "SessionSerializationError";
+    }
+}
+/**
+ * Creates a custom replacer function for JSON.stringify
+ *
+ * @remarks
+ * The replacer handles non-serializable values and circular references:
+ * - Functions become `[Function:name]` strings
+ * - Symbols become `[Symbol:description]` strings
+ * - Circular references become `[Circular:key]` strings
+ * - Undefined becomes null (JSON-compatible)
+ * - Uses WeakSet for circular reference tracking to avoid memory leaks
+ *
+ * @returns A replacer function for use with JSON.stringify
+ *
+ * @internal
+ */
+function createReplacer() {
+    const seen = new WeakSet();
+    return (key, value) => {
+        // CRITICAL: Check circular references FIRST
+        // Using WeakSet allows garbage collection of tracked objects
+        if (typeof value === "object" && value !== null) {
+            if (seen.has(value)) {
+                return `[Circular:${key}]`;
+            }
+            seen.add(value);
+        }
+        // Handle functions - cannot be serialized to JSON
+        if (typeof value === "function") {
+            return `[Function:${value.name || "anonymous"}]`;
+        }
+        // Handle symbols - cannot be serialized to JSON
+        if (typeof value === "symbol") {
+            return `[Symbol:${value.description || "unknown"}]`;
+        }
+        // Handle undefined - becomes null in JSON
+        if (value === undefined) {
+            return null;
+        }
+        return value;
+    };
+}
+/**
+ * Type guard for validating SessionState structure
+ *
+ * @remarks
+ * Validates that the parsed object has the required structure
+ * for a SessionState. Performs runtime type checking to ensure
+ * data integrity during deserialization.
+ *
+ * @param value - The value to validate
+ * @returns True if the value is a valid SessionState structure
+ *
+ * @internal
+ */
+function isValidSessionState(value) {
+    // Check if value is an object
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const obj = value;
+    // Check for required history property
+    if (!("history" in obj) || !Array.isArray(obj.history)) {
+        return false;
+    }
+    // Check for required lastResult property
+    if (!("lastResult" in obj)) {
+        return false;
+    }
+    // lastResult can be null or an object
+    if (obj.lastResult !== null && typeof obj.lastResult !== "object") {
+        return false;
+    }
+    return true;
+}
+/**
+ * Serialize a SessionState to JSON string
+ *
+ * @remarks
+ * Converts a SessionState object to a JSON string with special handling
+ * for non-serializable values and circular references. The resulting JSON
+ * is pretty-printed with 2-space indentation for readability.
+ *
+ * Handles edge cases from SDK message types:
+ * - `SDKUserMessage.tool_use_result` (unknown type)
+ * - `SDKResultMessage.result` (unknown type)
+ * - `SDKResultMessage.structured_output` (unknown type)
+ *
+ * Throws {@link SessionSerializationError} if serialization fails,
+ * with contextual information about the failure.
+ *
+ * @param state - The session state to serialize
+ * @returns JSON string representation of the session
+ * @throws {SessionSerializationError} If serialization fails
+ *
+ * @example
+ * ```ts
+ * import { serializeSession, deserializeSession } from 'groundswell';
+ *
+ * const state: SessionState = {
+ *   history: [],
+ *   lastResult: null
+ * };
+ *
+ * const json = serializeSession(state);
+ * console.log(json); // Pretty-printed JSON string
+ *
+ * // Round-trip serialization
+ * const restored = deserializeSession(json);
+ * expect(restored).toEqual(state);
+ * ```
+ */
+export function serializeSession(state) {
+    try {
+        const replacer = createReplacer();
+        // Pretty-print with 2-space indentation (matches session-store.ts pattern)
+        return JSON.stringify(state, replacer, 2);
+    }
+    catch (error) {
+        throw new SessionSerializationError(`Failed to serialize session: ${error instanceof Error ? error.message : "Unknown error"}`, "root", state);
+    }
+}
+/**
+ * Reconstruct a SessionState from JSON string
+ *
+ * @remarks
+ * Parses a JSON string and validates that it has the correct SessionState
+ * structure. Performs runtime type validation to ensure data integrity
+ * and catch corrupted or malformed session data early.
+ *
+ * Throws {@link SessionSerializationError} if deserialization fails or
+ * if the data doesn't match the expected SessionState structure.
+ *
+ * @param data - JSON string representation of the session
+ * @returns Reconstructed SessionState object
+ * @throws {SessionSerializationError} If deserialization fails or data is invalid
+ *
+ * @example
+ * ```ts
+ * import { serializeSession, deserializeSession } from 'groundswell';
+ *
+ * const state: SessionState = {
+ *   history: [],
+ *   lastResult: null
+ * };
+ *
+ * const json = serializeSession(state);
+ * const restored = deserializeSession(json);
+ *
+ * // Round-trip equality test
+ * expect(restored.history).toEqual(state.history);
+ * expect(restored.lastResult).toEqual(state.lastResult);
+ * ```
+ */
+export function deserializeSession(data) {
+    try {
+        const parsed = JSON.parse(data);
+        // CRITICAL: Validate structure before returning
+        if (!isValidSessionState(parsed)) {
+            throw new Error("Invalid session state structure: missing or malformed required properties");
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new SessionSerializationError(`Failed to deserialize session: ${error instanceof Error ? error.message : "Unknown error"}`, "root", data);
+    }
+}
+//# sourceMappingURL=session-serialization.js.map

package/dist/utils/session-serialization.js.map

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

package/dist/utils/workflow-error-utils.d.ts

@@ -0,0 +1,22 @@
+import type { WorkflowError } from '../types/error.js';
+/**
+ * Merge multiple WorkflowError objects into a single aggregated error.
+ *
+ * This is the default merger used when errorMergeStrategy is enabled for concurrent tasks.
+ * It aggregates information from all errors to provide a comprehensive view of failures.
+ *
+ * @param errors - Array of WorkflowError objects to merge
+ * @param taskName - Name of the task that spawned the concurrent workflows
+ * @param parentWorkflowId - ID of the parent workflow
+ * @param totalChildren - Total number of child workflows that were spawned
+ * @returns A merged WorkflowError containing aggregated information
+ *
+ * @example
+ * ```ts
+ * const errors: WorkflowError[] = [error1, error2, error3];
+ * const merged = mergeWorkflowErrors(errors, 'myTask', 'parent-123', 5);
+ * // Returns: WorkflowError with message "3 of 5 concurrent child workflows failed in task 'myTask'"
+ * ```
+ */
+export declare function mergeWorkflowErrors(errors: WorkflowError[], taskName: string, parentWorkflowId: string, totalChildren: number): WorkflowError;
+//# sourceMappingURL=workflow-error-utils.d.ts.map

package/dist/utils/workflow-error-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-error-utils.d.ts","sourceRoot":"","sources":["../../src/utils/workflow-error-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,MAAM,GACpB,aAAa,CA4Bf"}

package/dist/utils/workflow-error-utils.js

@@ -0,0 +1,45 @@
+/**
+ * Merge multiple WorkflowError objects into a single aggregated error.
+ *
+ * This is the default merger used when errorMergeStrategy is enabled for concurrent tasks.
+ * It aggregates information from all errors to provide a comprehensive view of failures.
+ *
+ * @param errors - Array of WorkflowError objects to merge
+ * @param taskName - Name of the task that spawned the concurrent workflows
+ * @param parentWorkflowId - ID of the parent workflow
+ * @param totalChildren - Total number of child workflows that were spawned
+ * @returns A merged WorkflowError containing aggregated information
+ *
+ * @example
+ * ```ts
+ * const errors: WorkflowError[] = [error1, error2, error3];
+ * const merged = mergeWorkflowErrors(errors, 'myTask', 'parent-123', 5);
+ * // Returns: WorkflowError with message "3 of 5 concurrent child workflows failed in task 'myTask'"
+ * ```
+ */
+export function mergeWorkflowErrors(errors, taskName, parentWorkflowId, totalChildren) {
+    // Create merged error message
+    const message = `${errors.length} of ${totalChildren} concurrent child workflows failed in task '${taskName}'`;
+    // Get all unique workflow IDs that failed
+    const failedWorkflowIds = [...new Set(errors.map((e) => e.workflowId))];
+    // Aggregate all logs
+    const allLogs = errors.flatMap((e) => e.logs);
+    // Create merged WorkflowError
+    const mergedError = {
+        message,
+        original: {
+            name: 'WorkflowAggregateError',
+            message,
+            errors,
+            totalChildren,
+            failedChildren: errors.length,
+            failedWorkflowIds,
+        },
+        workflowId: parentWorkflowId,
+        stack: errors[0]?.stack, // Use first error's stack trace
+        state: errors[0]?.state || {}, // Use first error's state
+        logs: allLogs,
+    };
+    return mergedError;
+}
+//# sourceMappingURL=workflow-error-utils.js.map

package/dist/utils/workflow-error-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-error-utils.js","sourceRoot":"","sources":["../../src/utils/workflow-error-utils.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAuB,EACvB,QAAgB,EAChB,gBAAwB,EACxB,aAAqB;IAErB,8BAA8B;IAC9B,MAAM,OAAO,GAAG,GAAG,MAAM,CAAC,MAAM,OAAO,aAAa,+CAA+C,QAAQ,GAAG,CAAC;IAE/G,0CAA0C;IAC1C,MAAM,iBAAiB,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAExE,qBAAqB;IACrB,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAE9C,8BAA8B;IAC9B,MAAM,WAAW,GAAkB;QACjC,OAAO;QACP,QAAQ,EAAE;YACR,IAAI,EAAE,wBAAwB;YAC9B,OAAO;YACP,MAAM;YACN,aAAa;YACb,cAAc,EAAE,MAAM,CAAC,MAAM;YAC7B,iBAAiB;SACP;QACZ,UAAU,EAAE,gBAAgB;QAC5B,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,gCAAgC;QACzD,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,IAAK,EAA8B,EAAE,0BAA0B;QACtF,IAAI,EAAE,OAAO;KACd,CAAC;IAEF,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundswell",
-  "version": "0.0.2",
+  "version": "1.0.0",
   "url": "https://github.com/groundswell-ai/groundswell",
   "description": "Hierarchical workflow orchestration engine with full observability",
   "keywords": [
@@ -23,6 +23,9 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -46,20 +49,46 @@
     "start:reflection": "tsx examples/examples/09-reflection.ts",
     "start:introspection": "tsx examples/examples/10-introspection.ts",
     "start:reparenting": "tsx examples/examples/11-reparenting-workflows.ts",
+    "start:harness-basic": "tsx examples/harnesses/01-basic-harness-usage.ts",
+    "start:harness-config": "tsx examples/harnesses/02-harness-configuration.ts",
+    "start:harness-switching": "tsx examples/harnesses/03-harness-switching.ts",
+    "start:harness-scenarios": "tsx examples/harnesses/04-multi-provider-scenarios.ts",
+    "start:harness-sessions": "tsx examples/harnesses/05-harness-sessions.ts",
+    "start:harness-features": "tsx examples/harnesses/06-harness-with-mcp-skills.ts",
+    "start:ink": "tsx examples/examples/ink-debugger-hello.tsx",
     "generate:llms": "npx tsx scripts/generate-llms-full.ts"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.71.1",
+    "@anthropic-ai/claude-agent-sdk": "^0.1.0",
+    "@earendil-works/pi-coding-agent": "^0.79.8",
+    "ink": "^6.6.0",
     "lru-cache": "^10.4.3",
-    "zod": "^3.23.0"
+    "react": "^19.0.0",
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.23.0"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.0",
+    "@semantic-release/npm": "^13.0.0",
+    "@semantic-release/release-notes-generator": "^14.0.0",
     "@types/node": "^20.0.0",
+    "@types/react": "^19.2.9",
+    "@vitest/coverage-v8": "^1.6.1",
+    "ink-testing-library": "^4.0.0",
+    "markdownlint-cli": "^0.47.0",
+    "semantic-release": "^25.0.0",
     "tsx": "^4.21.0",
     "typescript": "^5.2.0",
     "vitest": "^1.0.0"
   },
   "engines": {
-    "node": ">=18"
-  }
+    "node": ">=22.19"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ]
 }

package/.claude/commands/subtask-planning/prp-base-create.md

@@ -1,120 +0,0 @@
-# Create BASE PRP
-
-## Feature: $ARGUMENTS or $(tsk next) subtask
-
-## PRP Creation Mission
-
-Create a comprehensive PRP that enables **one-pass implementation success** through systematic research and context curation.
-
-
-**Critical Understanding**:
-You must start by reading and understanding the prp concepts plan/README.md
-Be aware that the executing AI agent only receives:
-- The PRP content you create
-- Its training data knowledge
-- Access to codebase files (but needs guidance on which ones)
-
-
-**Therefore**: Your research and context curation directly determines implementation success. Incomplete context = implementation failure.
-
-## Research Process
-
-> During the research process, create clear tasks and spawn as many agents and subagents as needed using the batch tools. The deeper research we do here the better the PRP will be. We optimize for chance of success, not for speed.
-
-1. **Codebase Analysis in depth**
-   - Create clear todos and spawn subagents to search the codebase for similar features/patterns. Think hard and plan your approach
-   - Identify all the necessary files to reference in the PRP
-   - Note all existing conventions to follow
-   - Check existing test patterns for validation approach, if none are found plan to find a new one
-   - Use the batch tools to spawn subagents to search the codebase for similar features/patterns
-
-2. **Internal Research at scale**
-   - Use relevant research and plan information in the `plan/M#P#T#S#` directory according to the current subtask
-   - Consider the scope of the subtask within the overall PRD. Respect the boundaries of scope of implementation for this task. Ensure cohesion across
-   previously completed tasks and guard against harming future task completion in your plan
-
-2. **External Research at scale**
-   - Create clear todos and spawn subagents with instructions to do deep research for similar features/patterns online and include urls to documentation and examples
-   - Library documentation (include specific URLs)
-   - Store all research in plans/\[M#P#T#S#]/research according to the current task and reference critical pieces of documentation in the PRP with clear
-   reasoning and instructions
-   - Implementation examples (GitHub/StackOverflow/blogs)
-   - New validation approach none found in existing codebase and user confirms they would like one added
-   - Best practices and common pitfalls found during research
-   - Use the batch tools to spawn subagents to search for similar features/patterns online and include urls to documentation and examples
-
-3. **User Clarification**
-   - Ask for clarification if you need it
-   - If no testing framework is found, ask the user if they would like to set one up
-   - If a fundamental misalignemnt of objectives across tasks is detected, halt and produce a thorough explanation of the problem at a 10th grade level
-
-## PRP Generation Process
-
-### Step 1: Choose Template
-
-Use `plan/templates/prp_base.md` as your template structure - it contains all necessary sections and formatting.
-
-### Step 2: Context Completeness Validation
-
-Before writing, apply the **"No Prior Knowledge" test** from the template:
-_"If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_
-
-### Step 3: Research Integration
-
-Transform your research findings into the template sections:
-
-**Goal Section**: Use research to define specific, measurable Feature Goal and concrete Deliverable
-**Context Section**: Populate YAML structure with your research findings - specific URLs, file patterns, gotchas
-**Implementation Tasks**: Create dependency-ordered tasks using information-dense keywords from codebase analysis
-**Validation Gates**: Use project-specific validation commands that you've verified work in this codebase
-
-### Step 4: Information Density Standards
-
-Ensure every reference is **specific and actionable**:
-
-- URLs include section anchors, not just domain names
-- File references include specific patterns to follow, not generic mentions
-- Task specifications include exact naming conventions and placement
-- Validation commands are project-specific and executable
-
-### Step 5: ULTRATHINK Before Writing
-
-After research completion, create comprehensive PRP writing plan using TodoWrite tool:
-
-- Plan how to structure each template section with your research findings
-- Identify gaps that need additional research
-- Create systematic approach to filling template with actionable context
-
-## Output
-
-Store the PRP at `plan/M#P#T#S#/PRP.md`
-Store documentation at `plan/M#P#T#S#/research/`
-
-## PRP Quality Gates
-
-### Context Completeness Check
-
-- [ ] Passes "No Prior Knowledge" test from template
-- [ ] All YAML references are specific and accessible
-- [ ] Implementation tasks include exact naming and placement guidance
-- [ ] Validation commands are project-specific and verified working
-
-### Template Structure Compliance
-
-- [ ] All required template sections completed
-- [ ] Goal section has specific Feature Goal, Deliverable, Success Definition
-- [ ] Implementation Tasks follow dependency ordering
-- [ ] Final Validation Checklist is comprehensive
-
-### Information Density Standards
-
-- [ ] No generic references - all are specific and actionable
-- [ ] File patterns point at specific examples to follow
-- [ ] URLs include section anchors for exact guidance
-- [ ] Task specifications use information-dense keywords from codebase
-
-## Success Metrics
-
-**Confidence Score**: Rate 1-10 for one-pass implementation success likelihood
-
-**Validation**: The completed PRP should enable an AI agent unfamiliar with the codebase to implement the feature successfully using only the PRP content and codebase access.

package/.claude/commands/subtask-planning/prp-base-execute.md

@@ -1,65 +0,0 @@
-# Execute BASE PRP
-
-## PRP File: $ARGUMENTS or $(tsk next) subtask information located at plans/M#P#T#S#/PRP.md
-
-## Mission: One-Pass Implementation Success
-
-PRPs enable working code on the first attempt through:
-
-- **Context Completeness**: Everything needed, nothing guessed
-- **Progressive Validation**: 4-level gates catch errors early
-- **Pattern Consistency**: Follow existing codebase approaches
-- Read PRPs/README.md to understand PRP concepts
-
-**Your Goal**: Transform the PRP into working code that passes all validation gates.
-
-## Execution Process
-
-1. **Load PRP**
-   - Read the specified PRP file completely
-   - Absorb all context, patterns, requirements and gather codebase intelligence
-   - Use the provided documentation references and file patterns, consume the right documentation before the appropriate todo/task
-   - Trust the PRP's context and guidance - it's designed for one-pass success
-   - If needed do additional codebase exploration and research as needed
-
-2. **ULTRATHINK & Plan**
-   - Create comprehensive implementation plan following the PRP's task order
-   - Break down into clear todos using TodoWrite tool
-   - Use subagents for parallel work when beneficial (always create prp inspired prompts for subagents when used)
-   - Follow the patterns referenced in the PRP
-   - Use specific file paths, class names, and method signatures from PRP context
-   - Never guess - always verify the codebase patterns and examples referenced in the PRP yourself
-
-3. **Execute Implementation**
-   - Follow the PRP's Implementation Tasks sequence, add more detail as needed, especially when using subagents
-   - Use the patterns and examples referenced in the PRP
-   - Create files in locations specified by the desired codebase tree
-   - Apply naming conventions from the task specifications and CLAUDE.md
-
-4. **Progressive Validation**
-
-   **Execute the level validation system from the PRP:**
-   - **Level 1**: Run syntax & style validation commands from PRP
-   - **Level 2**: Execute unit test validation from PRP
-   - **Level 3**: Run integration testing commands from PRP
-   - **Level 4**: Execute specified validation from PRP
-
-   **Each level must pass before proceeding to the next.**
-
-5. **Completion Verification**
-   - Work through the Final Validation Checklist in the PRP
-   - Verify all Success Criteria from the "What" section are met
-   - Confirm all Anti-Patterns were avoided
-   - Implementation is ready and working
-
-**Failure Protocol**: When validation fails, use the patterns and gotchas from the PRP to fix issues, then re-run validation until passing.
-
-If a fundamental issue with the plan is found, halt and produce a thorough explanation of the problem at a 10th grade level.
-
-Strictly output your results in this JSON format:
-
-```json
-{
-   "result": "success" | "error" | "issue",
-   "message": "Detailed explanation of the issue"
-}

package/.claude/commands/task-breakdown.md

@@ -1,94 +0,0 @@
-Act as a Lead Technical Architect and Project Management Synthesizer. You have already convened a panel of senior specialists (Security, DevOps, Backend, Frontend, and QA) who hold adversarial views on scope and complexity. Your job is not to output their debate, but to output their rigorous, unified consensus on how to decompose the attached PRD.
-
-Your Primary Goal: Assess the PRD to determine its hierarchy (Phase > Milestone > Task > Subtask) and decompose it into atomic, coherent work units.
-
-Hierarchy Definitions:
-
-Phase: Project-scope goals (e.g., MVP, V1.0). Weeks to months of effort.
-
-Milestone: Key objectives within a Phase. 1 to 12 weeks of effort.
-
-Task: Complete features within a Milestone. Days to weeks of effort.
-
-Subtask: Atomic implementation steps. 0.5, 1, or 2 Story Points (SP). Max 2 SP per subtask.
-
-Critical Constraints & Standard of Work (SOW):
-
-Coherence & Continuity (Priority):
-
-You must ensure architectural flow. Subtasks must not exist in a vacuum.
-
-If Subtask A defines a data schema, Subtask B must explicitly be told to consume that specific schema.
-
-Reference specific file paths, variable names, or API endpoints within the context_scope to ensure the implementing agent follows the chain of logic.
-
-Implicit TDD & Quality:
-
-Do not create subtasks for "Write Tests."
-
-Assume every subtask implies: "Write the failing test, implement the code, pass the test."
-
-Code is not complete without tests.
-
-The "Context Scope" Blinder:
-
-For every Subtask, the context_scope must be a strict set of instructions for a developer who cannot see the rest of the project.
-
-It must define Inputs (what data/interfaces are available from previous subtasks) and Outputs (what exact interface this subtask exposes).
-
-It must explicitly state Mocking Strategies to keep the subtask isolated.
-
-Process:
-
-Analyze the attached or referenced PRD.
-
-Determine the highest level of scope (Phase, Milestone, or Task) this PRD represents.
-
-Decompose strictly downwards to the Subtask level.
-
-Output Format:
-Output only a JSON object. No conversational text.
-
-```json
-{
-  "backlog": [
-    {
-      "type": "Phase",
-      "id": "P[#]",
-      "title": "Phase Title",
-      "status": "Planned | Researching | Ready | Implementing | Complete | Failed",
-      "description": "High level goal.",
-      "milestones": [
-        {
-          "type": "Milestone",
-          "id": "P[#].M[#]",
-          "title": "Milestone Title",
-          "status": "Planned",
-          "description": "Key objective.",
-          "tasks": [
-            {
-              "type": "Task",
-              "id": "P[#].M[#].T[#]",
-              "title": "Task Title",
-              "status": "Planned",
-              "description": "Feature definition.",
-              "subtasks": [
-                {
-                  "type": "Subtask",
-                  "id": "P[#].M[#].T[#].S[#]",
-                  "title": "Subtask Title",
-                  "status": "Planned",
-                  "story_points": 1,
-                  "dependencies": ["ID of prerequisite subtask"],
-                  "context_scope": "CONTRACT DEFINITION:\n1. INPUT: [Specific data structure/variable] from [Dependency ID].\n2. LOGIC: Implement [PRD Section X] logic. Mock [Service Y] for isolation.\n3. OUTPUT: Return [Result Object/Interface] for consumption by [Next Subtask ID]."
-                }
-              ]
-            }
-          ]
-        }
-      ]
-    }
-  ]
-}
-```
-

package/.claude/settings.local.json

@@ -1,9 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(mkdir:*)"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}