@riotprompt/riotplan 0.0.2

package/.kodrdriv-test-cache.json

@@ -0,0 +1,6 @@
+{
+  "/Users/tobrien/gitw/kjerneverk/riotplan": {
+    "lastTestRun": 1768074377328,
+    "lastCommitHash": "42a1f26de39443084ae4f737e587726ded966f7e"
+  }
+}

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Tim O'Brien
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,170 @@
+# riotplan
+
+Framework for long-lived, stateful AI workflows (plans).
+
+## What is a Plan?
+
+A **plan** is a structured way to manage multi-step AI-assisted tasks that:
+
+- **Span multiple sessions** - Work on a task over days or weeks
+- **Have persistent state** - Track progress in STATUS.md
+- **Are organized into steps** - Numbered files (01-STEP.md, 02-STEP.md)
+- **Can be interrupted and resumed** - Pick up where you left off
+- **Support collaboration** - Human reviews, feedback loops
+
+## Plan Structure
+
+```
+my-plan/
+├── my-plan-prompt.md     # Meta-prompt (prompt-of-prompts)
+├── SUMMARY.md            # Overview of the approach
+├── EXECUTION_PLAN.md     # Step-by-step strategy
+├── STATUS.md             # Current state (auto-updated)
+├── plan/                 # Step files
+│   ├── 01-first-step.md
+│   ├── 02-second-step.md
+│   └── ...
+└── analysis/             # Analysis output (optional)
+```
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `{code}-prompt.md` | Initial meta-prompt that creates the plan |
+| `SUMMARY.md` | High-level overview of the approach |
+| `EXECUTION_PLAN.md` | Detailed execution strategy |
+| `STATUS.md` | Current state, progress tracking |
+| `01-*.md`, `02-*.md` | Individual step prompts |
+
+## Real-World Examples
+
+Plans in the wild:
+
+```
+grunnverk/prompts/
+├── big-splitup/           # Codebase restructuring
+├── commit-splitting/      # Feature implementation
+├── parallel-execution/    # Complex feature with phases
+├── shared-utils/          # Package extraction
+└── ai-service/            # Service extraction
+```
+
+## Installation
+
+```bash
+npm install riotplan
+```
+
+## Usage (Coming Soon)
+
+```typescript
+import { loadPlan, resumePlan } from 'riotplan';
+
+// Load an existing plan
+const plan = await loadPlan('./prompts/my-feature');
+
+console.log(plan.metadata.code);     // 'my-feature'
+console.log(plan.state.status);      // 'in_progress'
+console.log(plan.state.currentStep); // 3
+
+// Resume execution
+const result = await resumePlan(plan);
+```
+
+## Creating a Plan
+
+```typescript
+import { createPlan } from 'riotplan';
+
+const plan = await createPlan({
+  code: 'my-feature',
+  name: 'My Feature Implementation',
+  path: './prompts/my-feature',
+  description: 'Implement the new feature with proper testing',
+  steps: [
+    { title: 'Analysis', description: 'Analyze requirements' },
+    { title: 'Design', description: 'Design the solution' },
+    { title: 'Implementation', description: 'Build it' },
+    { title: 'Testing', description: 'Verify it works' },
+    { title: 'Documentation', description: 'Document it' },
+  ]
+});
+```
+
+## STATUS.md Format
+
+```markdown
+# My Feature - Execution Status
+
+## Current State
+
+| Field | Value |
+|-------|-------|
+| **Status** | `in_progress` |
+| **Current Step** | 03-implementation |
+| **Last Completed** | 02-design |
+| **Started At** | 2026-01-08 |
+| **Last Updated** | 2026-01-10 |
+
+## Step Progress
+
+| Step | Name | Status | Started | Completed | Notes |
+|------|------|--------|---------|-----------|-------|
+| 01 | Analysis | ✅ Completed | 2026-01-08 | 2026-01-08 | - |
+| 02 | Design | ✅ Completed | 2026-01-08 | 2026-01-09 | - |
+| 03 | Implementation | 🔄 In Progress | 2026-01-09 | - | 50% done |
+| 04 | Testing | ⬜ Pending | - | - | - |
+| 05 | Documentation | ⬜ Pending | - | - | - |
+
+## Blockers
+
+_No blockers currently._
+
+## Issues
+
+_No issues encountered._
+```
+
+## Roadmap
+
+### v0.1.0 - Core Functionality
+- [ ] Load plans from directories
+- [ ] Parse STATUS.md
+- [ ] Generate STATUS.md
+- [ ] Step file discovery
+
+### v0.2.0 - Execution
+- [ ] Execute individual steps
+- [ ] Resume from checkpoint
+- [ ] Update state automatically
+
+### v0.3.0 - Integration
+- [ ] CLI (riotplan-cli)
+- [ ] Agentic execution
+- [ ] Riotprompt integration
+
+## Related Packages
+
+- `riotprompt` - Prompt modeling for single interactions
+- `agentic` - Multi-turn conversation framework
+- `execution` - LLM provider interfaces
+- `riotplan-cli` - Command-line interface (coming soon)
+
+## Philosophy
+
+Plans bridge the gap between:
+- **Prompts** (single interactions)
+- **Agentic conversations** (multi-turn sessions)
+- **Long-running workflows** (days/weeks of work)
+
+A plan provides structure for complex, iterative AI-assisted work where:
+- The work can't be done in one session
+- Progress needs to be tracked
+- Humans need to review and provide feedback
+- The approach may evolve based on findings
+
+## License
+
+Apache-2.0
+

package/dist/index.cjs

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const PLAN_CONVENTIONS = {
+  /** Meta-prompt file patterns */
+  metaPromptPatterns: [
+    "{code}-prompt.md",
+    "prompt-of-prompts.md",
+    "{code}.md"
+  ],
+  /** Step file pattern */
+  stepPattern: /^(\d{2})-(.+)\.md$/,
+  /** Standard files */
+  standardFiles: {
+    summary: "SUMMARY.md",
+    status: "STATUS.md",
+    executionPlan: "EXECUTION_PLAN.md",
+    readme: "README.md"
+  },
+  /** Standard directories */
+  standardDirs: {
+    plan: "plan",
+    analysis: "analysis",
+    architecture: "architecture",
+    implementation: "implementation",
+    testing: "testing"
+  },
+  /** Status emoji mapping */
+  statusEmoji: {
+    pending: "⬜",
+    in_progress: "🔄",
+    completed: "✅",
+    failed: "❌",
+    blocked: "⏸️",
+    skipped: "⏭️"
+  }
+};
+const VERSION = "0.0.1";
+async function loadPlan(_path) {
+  throw new Error(
+    "riotplan.loadPlan is not yet implemented. Coming in v0.1.0!"
+  );
+}
+async function createPlan(_config) {
+  throw new Error(
+    "riotplan.createPlan is not yet implemented. Coming in v0.1.0!"
+  );
+}
+function parseStatus(_content) {
+  throw new Error(
+    "riotplan.parseStatus is not yet implemented. Coming in v0.1.0!"
+  );
+}
+function generateStatus(_plan) {
+  throw new Error(
+    "riotplan.generateStatus is not yet implemented. Coming in v0.1.0!"
+  );
+}
+async function executeStep(_plan, _stepNumber, _context) {
+  throw new Error(
+    "riotplan.executeStep is not yet implemented. Coming in v0.1.0!"
+  );
+}
+async function resumePlan(_plan, _context) {
+  throw new Error(
+    "riotplan.resumePlan is not yet implemented. Coming in v0.1.0!"
+  );
+}
+function updatePlanState(_plan, _stepNumber, _result) {
+  throw new Error(
+    "riotplan.updatePlanState is not yet implemented. Coming in v0.1.0!"
+  );
+}
+exports.PLAN_CONVENTIONS = PLAN_CONVENTIONS;
+exports.VERSION = VERSION;
+exports.createPlan = createPlan;
+exports.executeStep = executeStep;
+exports.generateStatus = generateStatus;
+exports.loadPlan = loadPlan;
+exports.parseStatus = parseStatus;
+exports.resumePlan = resumePlan;
+exports.updatePlanState = updatePlanState;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/types.ts","../src/index.ts"],"sourcesContent":["/**\n * RiotPlan Type Definitions\n *\n * Types for long-lived, stateful AI workflows (plans).\n *\n * A plan consists of:\n * - A directory (the plan code/name)\n * - A meta-prompt (prompt-of-prompts)\n * - Numbered step files (01-STEP.md, 02-STEP.md, etc.)\n * - Status tracking (STATUS.md)\n * - Execution strategy (EXECUTION_PLAN.md)\n * - Summary (SUMMARY.md)\n * - Optional analysis directory\n */\n\n// ===== TASK STATUS =====\n\n/**\n * Status of a task, phase, or step\n */\nexport type TaskStatus =\n  | \"pending\" // Not started (⬜)\n  | \"in_progress\" // Currently active (🔄)\n  | \"completed\" // Done (✅)\n  | \"failed\" // Failed with error (❌)\n  | \"blocked\" // Waiting on dependency (⏸️)\n  | \"skipped\"; // Intentionally skipped (⏭️)\n\n/**\n * Priority level\n */\nexport type Priority = \"high\" | \"medium\" | \"low\";\n\n// ===== PLAN STRUCTURE =====\n\n/**\n * A single step in a plan (corresponds to a numbered file like 01-STEP.md)\n */\nexport interface PlanStep {\n  /** Step number (1, 2, 3...) */\n  number: number;\n\n  /** Step code/slug (extracted from filename, e.g., \"execution-interfaces\") */\n  code: string;\n\n  /** Full filename (e.g., \"01-execution-interfaces.md\") */\n  filename: string;\n\n  /** Human-readable title */\n  title: string;\n\n  /** Step description */\n  description?: string;\n\n  /** Current status */\n  status: TaskStatus;\n\n  /** Dependencies on other steps (by number) */\n  dependencies?: number[];\n\n  /** When this step was started */\n  startedAt?: Date;\n\n  /** When this step was completed */\n  completedAt?: Date;\n\n  /** Duration in milliseconds */\n  duration?: number;\n\n  /** Notes or issues encountered */\n  notes?: string;\n\n  /** Path to the step file */\n  filePath: string;\n}\n\n/**\n * A phase grouping multiple steps\n */\nexport interface PlanPhase {\n  /** Phase number */\n  number: number;\n\n  /** Phase name */\n  name: string;\n\n  /** Description */\n  description?: string;\n\n  /** Steps in this phase */\n  steps: number[]; // Step numbers\n\n  /** Phase status (derived from step statuses) */\n  status: TaskStatus;\n\n  /** Estimated duration */\n  estimatedDuration?: string;\n\n  /** Actual duration */\n  actualDuration?: string;\n}\n\n/**\n * Blocker preventing progress\n */\nexport interface Blocker {\n  /** Unique identifier */\n  id: string;\n\n  /** Description of the blocker */\n  description: string;\n\n  /** Severity */\n  severity: Priority;\n\n  /** Affected steps */\n  affectedSteps: number[];\n\n  /** When created */\n  createdAt: Date;\n\n  /** When resolved */\n  resolvedAt?: Date;\n\n  /** Resolution notes */\n  resolution?: string;\n}\n\n/**\n * Issue encountered during execution\n */\nexport interface Issue {\n  /** Unique identifier */\n  id: string;\n\n  /** Issue title */\n  title: string;\n\n  /** Description */\n  description: string;\n\n  /** Severity */\n  severity: Priority;\n\n  /** Related step */\n  step?: number;\n\n  /** When encountered */\n  createdAt: Date;\n\n  /** When resolved */\n  resolvedAt?: Date;\n\n  /** How it was resolved */\n  resolution?: string;\n}\n\n// ===== PLAN METADATA =====\n\n/**\n * Plan metadata from the directory and files\n */\nexport interface PlanMetadata {\n  /** Plan code (directory name, e.g., \"big-splitup\") */\n  code: string;\n\n  /** Human-readable name */\n  name: string;\n\n  /** Description from SUMMARY.md or meta-prompt */\n  description?: string;\n\n  /** Version (for tracking changes to the plan itself) */\n  version?: string;\n\n  /** Author */\n  author?: string;\n\n  /** Tags for categorization */\n  tags?: string[];\n\n  /** When the plan was created */\n  createdAt?: Date;\n\n  /** Path to the plan directory */\n  path: string;\n}\n\n// ===== PLAN FILES =====\n\n/**\n * Standard plan files\n */\nexport interface PlanFiles {\n  /** Meta-prompt file (e.g., \"big-splitup-prompt.md\" or \"prompt-of-prompts.md\") */\n  metaPrompt?: string;\n\n  /** Summary file */\n  summary?: string;\n\n  /** Status file */\n  status?: string;\n\n  /** Execution plan file */\n  executionPlan?: string;\n\n  /** README file */\n  readme?: string;\n\n  /** Step files in order */\n  steps: string[];\n\n  /** Analysis directory */\n  analysisDir?: string;\n\n  /** Other directories (architecture/, implementation/, testing/) */\n  subdirectories: string[];\n}\n\n// ===== PLAN STATE =====\n\n/**\n * Current state of plan execution\n */\nexport interface PlanState {\n  /** Overall plan status */\n  status: TaskStatus;\n\n  /** Current step being executed */\n  currentStep?: number;\n\n  /** Last completed step */\n  lastCompletedStep?: number;\n\n  /** When execution started */\n  startedAt?: Date;\n\n  /** When last updated */\n  lastUpdatedAt: Date;\n\n  /** When completed */\n  completedAt?: Date;\n\n  /** Active blockers */\n  blockers: Blocker[];\n\n  /** Issues encountered */\n  issues: Issue[];\n\n  /** Progress percentage (0-100) */\n  progress: number;\n}\n\n// ===== COMPLETE PLAN =====\n\n/**\n * Complete plan definition\n */\nexport interface Plan {\n  /** Plan metadata */\n  metadata: PlanMetadata;\n\n  /** Plan files */\n  files: PlanFiles;\n\n  /** Plan steps */\n  steps: PlanStep[];\n\n  /** Plan phases (optional grouping) */\n  phases?: PlanPhase[];\n\n  /** Current state */\n  state: PlanState;\n}\n\n// ===== EXECUTION =====\n\n/**\n * Context for plan execution\n */\nexport interface PlanContext {\n  /** Working directory */\n  workingDirectory: string;\n\n  /** The plan being executed */\n  plan: Plan;\n\n  /** Logger instance */\n  logger?: any;\n\n  /** Storage for artifacts */\n  storage?: any;\n\n  /** Environment variables */\n  env?: Record<string, string>;\n}\n\n/**\n * Result of executing a step\n */\nexport interface StepResult {\n  /** Whether the step succeeded */\n  success: boolean;\n\n  /** Step number */\n  step: number;\n\n  /** Output from execution */\n  output?: string;\n\n  /** Error if failed */\n  error?: Error;\n\n  /** Duration in milliseconds */\n  duration: number;\n\n  /** Artifacts produced */\n  artifacts?: string[];\n}\n\n/**\n * Result of executing a plan\n */\nexport interface PlanResult {\n  /** Whether the plan completed successfully */\n  success: boolean;\n\n  /** Steps that were executed */\n  executedSteps: number[];\n\n  /** Steps that succeeded */\n  completedSteps: number[];\n\n  /** Steps that failed */\n  failedSteps: number[];\n\n  /** Steps that were skipped */\n  skippedSteps: number[];\n\n  /** Total duration */\n  duration: number;\n\n  /** Final plan state */\n  finalState: PlanState;\n}\n\n// ===== SERIALIZATION =====\n\n/**\n * STATUS.md schema for parsing/generating\n */\nexport interface StatusDocument {\n  /** Document title */\n  title: string;\n\n  /** Current state summary */\n  currentState: {\n    status: TaskStatus;\n    currentStep?: string;\n    lastCompleted?: string;\n    startedAt?: string;\n    lastUpdated?: string;\n  };\n\n  /** Step progress table */\n  stepProgress: Array<{\n    step: string;\n    name: string;\n    status: TaskStatus;\n    started?: string;\n    completed?: string;\n    notes?: string;\n  }>;\n\n  /** Blockers section */\n  blockers: string[];\n\n  /** Issues section */\n  issues: string[];\n\n  /** Notes section */\n  notes?: string;\n}\n\n/**\n * EXECUTION_PLAN.md schema\n */\nexport interface ExecutionPlanDocument {\n  /** Strategy description */\n  strategy: string;\n\n  /** Prerequisites */\n  prerequisites: string[];\n\n  /** Phases with their steps */\n  phases: Array<{\n    name: string;\n    description: string;\n    steps: string[];\n  }>;\n\n  /** Quality gates */\n  qualityGates?: string[];\n\n  /** Rollback instructions */\n  rollback?: string;\n}\n\n// ===== PLAN CONVENTIONS =====\n\n/**\n * File naming conventions\n */\nexport const PLAN_CONVENTIONS = {\n    /** Meta-prompt file patterns */\n    metaPromptPatterns: [\n        \"{code}-prompt.md\",\n        \"prompt-of-prompts.md\",\n        \"{code}.md\",\n    ],\n\n    /** Step file pattern */\n    stepPattern: /^(\\d{2})-(.+)\\.md$/,\n\n    /** Standard files */\n    standardFiles: {\n        summary: \"SUMMARY.md\",\n        status: \"STATUS.md\",\n        executionPlan: \"EXECUTION_PLAN.md\",\n        readme: \"README.md\",\n    },\n\n    /** Standard directories */\n    standardDirs: {\n        plan: \"plan\",\n        analysis: \"analysis\",\n        architecture: \"architecture\",\n        implementation: \"implementation\",\n        testing: \"testing\",\n    },\n\n    /** Status emoji mapping */\n    statusEmoji: {\n        pending: \"⬜\",\n        in_progress: \"🔄\",\n        completed: \"✅\",\n        failed: \"❌\",\n        blocked: \"⏸️\",\n        skipped: \"⏭️\",\n    } as Record<TaskStatus, string>,\n} as const;\n\n","/**\n * RiotPlan - Framework for long-lived, stateful AI workflows\n *\n * A plan is a structured way to manage multi-step AI-assisted tasks that:\n * - Span multiple sessions/days\n * - Have persistent state (STATUS.md)\n * - Are organized into numbered steps\n * - Can be interrupted and resumed\n * - Track progress with checkboxes and statuses\n *\n * @example Plan directory structure:\n * ```\n * my-plan/\n * ├── my-plan-prompt.md     # Meta-prompt (prompt-of-prompts)\n * ├── SUMMARY.md            # Overview of the approach\n * ├── EXECUTION_PLAN.md     # Step-by-step strategy\n * ├── STATUS.md             # Current state (auto-updated)\n * ├── plan/                 # Step files (optional subdirectory)\n * │   ├── 01-first-step.md\n * │   ├── 02-second-step.md\n * │   └── ...\n * └── analysis/             # Analysis output (optional)\n * ```\n */\n\n// ===== EXPORTS =====\n\n// Types\nexport type {\n    TaskStatus,\n    Priority,\n    PlanStep,\n    PlanPhase,\n    Blocker,\n    Issue,\n    PlanMetadata,\n    PlanFiles,\n    PlanState,\n    Plan,\n    PlanContext,\n    StepResult,\n    PlanResult,\n    StatusDocument,\n    ExecutionPlanDocument,\n} from \"./types.js\";\n\n// Constants\nexport { PLAN_CONVENTIONS } from \"./types.js\";\n\n// Version\nexport const VERSION = \"0.0.1\";\n\n// ===== STUB IMPLEMENTATIONS =====\n// These will be implemented as the project develops\n\n/**\n * Load a plan from a directory\n *\n * @param path - Path to the plan directory\n * @returns The loaded plan\n *\n * @example\n * ```typescript\n * const plan = await loadPlan('./prompts/big-splitup');\n * console.log(plan.metadata.code); // 'big-splitup'\n * console.log(plan.steps.length);  // 11\n * ```\n *\n * @stub Not yet implemented\n */\nexport async function loadPlan(_path: string): Promise<never> {\n    throw new Error(\n        \"riotplan.loadPlan is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Create a new plan\n *\n * @param config - Plan configuration\n * @returns The created plan\n *\n * @example\n * ```typescript\n * const plan = await createPlan({\n *   code: 'my-feature',\n *   name: 'My Feature Implementation',\n *   path: './prompts/my-feature',\n *   steps: [\n *     { title: 'Setup', description: 'Initial setup' },\n *     { title: 'Implementation', description: 'Core work' },\n *     { title: 'Testing', description: 'Verify it works' },\n *   ]\n * });\n * ```\n *\n * @stub Not yet implemented\n */\nexport async function createPlan(_config: {\n  code: string;\n  name: string;\n  path: string;\n  description?: string;\n  steps?: Array<{ title: string; description?: string }>;\n}): Promise<never> {\n    throw new Error(\n        \"riotplan.createPlan is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Parse a STATUS.md file\n *\n * @param content - The STATUS.md content\n * @returns Parsed status document\n *\n * @stub Not yet implemented\n */\nexport function parseStatus(_content: string): never {\n    throw new Error(\n        \"riotplan.parseStatus is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Generate a STATUS.md file\n *\n * @param plan - The plan to generate status for\n * @returns STATUS.md content\n *\n * @stub Not yet implemented\n */\nexport function generateStatus(_plan: unknown): never {\n    throw new Error(\n        \"riotplan.generateStatus is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Execute a plan step\n *\n * @param plan - The plan\n * @param stepNumber - Step to execute\n * @param context - Execution context\n * @returns Step result\n *\n * @stub Not yet implemented\n */\nexport async function executeStep(\n    _plan: unknown,\n    _stepNumber: number,\n    _context?: unknown\n): Promise<never> {\n    throw new Error(\n        \"riotplan.executeStep is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Resume a plan from its current state\n *\n * @param plan - The plan to resume\n * @param context - Execution context\n * @returns Plan result\n *\n * @stub Not yet implemented\n */\nexport async function resumePlan(\n    _plan: unknown,\n    _context?: unknown\n): Promise<never> {\n    throw new Error(\n        \"riotplan.resumePlan is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Update plan state after step completion\n *\n * @param plan - The plan\n * @param stepNumber - Completed step\n * @param result - Step result\n * @returns Updated plan\n *\n * @stub Not yet implemented\n */\nexport function updatePlanState(\n    _plan: unknown,\n    _stepNumber: number,\n    _result: unknown\n): never {\n    throw new Error(\n        \"riotplan.updatePlanState is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n"],"names":[],"mappings":";;AA6ZO,MAAM,mBAAmB;AAAA;AAAA,EAE5B,oBAAoB;AAAA,IAChB;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAAA;AAAA,EAIJ,aAAa;AAAA;AAAA,EAGb,eAAe;AAAA,IACX,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,eAAe;AAAA,IACf,QAAQ;AAAA,EAAA;AAAA;AAAA,EAIZ,cAAc;AAAA,IACV,MAAM;AAAA,IACN,UAAU;AAAA,IACV,cAAc;AAAA,IACd,gBAAgB;AAAA,IAChB,SAAS;AAAA,EAAA;AAAA;AAAA,EAIb,aAAa;AAAA,IACT,SAAS;AAAA,IACT,aAAa;AAAA,IACb,WAAW;AAAA,IACX,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,SAAS;AAAA,EAAA;AAEjB;AChZO,MAAM,UAAU;AAoBvB,eAAsB,SAAS,OAA+B;AAC1D,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAwBA,eAAsB,WAAW,SAMd;AACf,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAUO,SAAS,YAAY,UAAyB;AACjD,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAUO,SAAS,eAAe,OAAuB;AAClD,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAYA,eAAsB,YAClB,OACA,aACA,UACc;AACd,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAWA,eAAsB,WAClB,OACA,UACc;AACd,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAYO,SAAS,gBACZ,OACA,aACA,SACK;AACL,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,440 @@
+/**
+ * Blocker preventing progress
+ */
+export declare interface Blocker {
+    /** Unique identifier */
+    id: string;
+    /** Description of the blocker */
+    description: string;
+    /** Severity */
+    severity: Priority;
+    /** Affected steps */
+    affectedSteps: number[];
+    /** When created */
+    createdAt: Date;
+    /** When resolved */
+    resolvedAt?: Date;
+    /** Resolution notes */
+    resolution?: string;
+}
+
+/**
+ * Create a new plan
+ *
+ * @param config - Plan configuration
+ * @returns The created plan
+ *
+ * @example
+ * ```typescript
+ * const plan = await createPlan({
+ *   code: 'my-feature',
+ *   name: 'My Feature Implementation',
+ *   path: './prompts/my-feature',
+ *   steps: [
+ *     { title: 'Setup', description: 'Initial setup' },
+ *     { title: 'Implementation', description: 'Core work' },
+ *     { title: 'Testing', description: 'Verify it works' },
+ *   ]
+ * });
+ * ```
+ *
+ * @stub Not yet implemented
+ */
+export declare function createPlan(_config: {
+    code: string;
+    name: string;
+    path: string;
+    description?: string;
+    steps?: Array<{
+        title: string;
+        description?: string;
+    }>;
+}): Promise<never>;
+
+/**
+ * Execute a plan step
+ *
+ * @param plan - The plan
+ * @param stepNumber - Step to execute
+ * @param context - Execution context
+ * @returns Step result
+ *
+ * @stub Not yet implemented
+ */
+export declare function executeStep(_plan: unknown, _stepNumber: number, _context?: unknown): Promise<never>;
+
+/**
+ * EXECUTION_PLAN.md schema
+ */
+export declare interface ExecutionPlanDocument {
+    /** Strategy description */
+    strategy: string;
+    /** Prerequisites */
+    prerequisites: string[];
+    /** Phases with their steps */
+    phases: Array<{
+        name: string;
+        description: string;
+        steps: string[];
+    }>;
+    /** Quality gates */
+    qualityGates?: string[];
+    /** Rollback instructions */
+    rollback?: string;
+}
+
+/**
+ * Generate a STATUS.md file
+ *
+ * @param plan - The plan to generate status for
+ * @returns STATUS.md content
+ *
+ * @stub Not yet implemented
+ */
+export declare function generateStatus(_plan: unknown): never;
+
+/**
+ * Issue encountered during execution
+ */
+export declare interface Issue {
+    /** Unique identifier */
+    id: string;
+    /** Issue title */
+    title: string;
+    /** Description */
+    description: string;
+    /** Severity */
+    severity: Priority;
+    /** Related step */
+    step?: number;
+    /** When encountered */
+    createdAt: Date;
+    /** When resolved */
+    resolvedAt?: Date;
+    /** How it was resolved */
+    resolution?: string;
+}
+
+/**
+ * Load a plan from a directory
+ *
+ * @param path - Path to the plan directory
+ * @returns The loaded plan
+ *
+ * @example
+ * ```typescript
+ * const plan = await loadPlan('./prompts/big-splitup');
+ * console.log(plan.metadata.code); // 'big-splitup'
+ * console.log(plan.steps.length);  // 11
+ * ```
+ *
+ * @stub Not yet implemented
+ */
+export declare function loadPlan(_path: string): Promise<never>;
+
+/**
+ * Parse a STATUS.md file
+ *
+ * @param content - The STATUS.md content
+ * @returns Parsed status document
+ *
+ * @stub Not yet implemented
+ */
+export declare function parseStatus(_content: string): never;
+
+/**
+ * Complete plan definition
+ */
+export declare interface Plan {
+    /** Plan metadata */
+    metadata: PlanMetadata;
+    /** Plan files */
+    files: PlanFiles;
+    /** Plan steps */
+    steps: PlanStep[];
+    /** Plan phases (optional grouping) */
+    phases?: PlanPhase[];
+    /** Current state */
+    state: PlanState;
+}
+
+/**
+ * File naming conventions
+ */
+export declare const PLAN_CONVENTIONS: {
+    /** Meta-prompt file patterns */
+    readonly metaPromptPatterns: readonly ["{code}-prompt.md", "prompt-of-prompts.md", "{code}.md"];
+    /** Step file pattern */
+    readonly stepPattern: RegExp;
+    /** Standard files */
+    readonly standardFiles: {
+        readonly summary: "SUMMARY.md";
+        readonly status: "STATUS.md";
+        readonly executionPlan: "EXECUTION_PLAN.md";
+        readonly readme: "README.md";
+    };
+    /** Standard directories */
+    readonly standardDirs: {
+        readonly plan: "plan";
+        readonly analysis: "analysis";
+        readonly architecture: "architecture";
+        readonly implementation: "implementation";
+        readonly testing: "testing";
+    };
+    /** Status emoji mapping */
+    readonly statusEmoji: Record<TaskStatus, string>;
+};
+
+/**
+ * Context for plan execution
+ */
+export declare interface PlanContext {
+    /** Working directory */
+    workingDirectory: string;
+    /** The plan being executed */
+    plan: Plan;
+    /** Logger instance */
+    logger?: any;
+    /** Storage for artifacts */
+    storage?: any;
+    /** Environment variables */
+    env?: Record<string, string>;
+}
+
+/**
+ * Standard plan files
+ */
+export declare interface PlanFiles {
+    /** Meta-prompt file (e.g., "big-splitup-prompt.md" or "prompt-of-prompts.md") */
+    metaPrompt?: string;
+    /** Summary file */
+    summary?: string;
+    /** Status file */
+    status?: string;
+    /** Execution plan file */
+    executionPlan?: string;
+    /** README file */
+    readme?: string;
+    /** Step files in order */
+    steps: string[];
+    /** Analysis directory */
+    analysisDir?: string;
+    /** Other directories (architecture/, implementation/, testing/) */
+    subdirectories: string[];
+}
+
+/**
+ * Plan metadata from the directory and files
+ */
+export declare interface PlanMetadata {
+    /** Plan code (directory name, e.g., "big-splitup") */
+    code: string;
+    /** Human-readable name */
+    name: string;
+    /** Description from SUMMARY.md or meta-prompt */
+    description?: string;
+    /** Version (for tracking changes to the plan itself) */
+    version?: string;
+    /** Author */
+    author?: string;
+    /** Tags for categorization */
+    tags?: string[];
+    /** When the plan was created */
+    createdAt?: Date;
+    /** Path to the plan directory */
+    path: string;
+}
+
+/**
+ * A phase grouping multiple steps
+ */
+export declare interface PlanPhase {
+    /** Phase number */
+    number: number;
+    /** Phase name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Steps in this phase */
+    steps: number[];
+    /** Phase status (derived from step statuses) */
+    status: TaskStatus;
+    /** Estimated duration */
+    estimatedDuration?: string;
+    /** Actual duration */
+    actualDuration?: string;
+}
+
+/**
+ * Result of executing a plan
+ */
+export declare interface PlanResult {
+    /** Whether the plan completed successfully */
+    success: boolean;
+    /** Steps that were executed */
+    executedSteps: number[];
+    /** Steps that succeeded */
+    completedSteps: number[];
+    /** Steps that failed */
+    failedSteps: number[];
+    /** Steps that were skipped */
+    skippedSteps: number[];
+    /** Total duration */
+    duration: number;
+    /** Final plan state */
+    finalState: PlanState;
+}
+
+/**
+ * Current state of plan execution
+ */
+export declare interface PlanState {
+    /** Overall plan status */
+    status: TaskStatus;
+    /** Current step being executed */
+    currentStep?: number;
+    /** Last completed step */
+    lastCompletedStep?: number;
+    /** When execution started */
+    startedAt?: Date;
+    /** When last updated */
+    lastUpdatedAt: Date;
+    /** When completed */
+    completedAt?: Date;
+    /** Active blockers */
+    blockers: Blocker[];
+    /** Issues encountered */
+    issues: Issue[];
+    /** Progress percentage (0-100) */
+    progress: number;
+}
+
+/**
+ * A single step in a plan (corresponds to a numbered file like 01-STEP.md)
+ */
+export declare interface PlanStep {
+    /** Step number (1, 2, 3...) */
+    number: number;
+    /** Step code/slug (extracted from filename, e.g., "execution-interfaces") */
+    code: string;
+    /** Full filename (e.g., "01-execution-interfaces.md") */
+    filename: string;
+    /** Human-readable title */
+    title: string;
+    /** Step description */
+    description?: string;
+    /** Current status */
+    status: TaskStatus;
+    /** Dependencies on other steps (by number) */
+    dependencies?: number[];
+    /** When this step was started */
+    startedAt?: Date;
+    /** When this step was completed */
+    completedAt?: Date;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Notes or issues encountered */
+    notes?: string;
+    /** Path to the step file */
+    filePath: string;
+}
+
+/**
+ * Priority level
+ */
+export declare type Priority = "high" | "medium" | "low";
+
+/**
+ * Resume a plan from its current state
+ *
+ * @param plan - The plan to resume
+ * @param context - Execution context
+ * @returns Plan result
+ *
+ * @stub Not yet implemented
+ */
+export declare function resumePlan(_plan: unknown, _context?: unknown): Promise<never>;
+
+/**
+ * STATUS.md schema for parsing/generating
+ */
+export declare interface StatusDocument {
+    /** Document title */
+    title: string;
+    /** Current state summary */
+    currentState: {
+        status: TaskStatus;
+        currentStep?: string;
+        lastCompleted?: string;
+        startedAt?: string;
+        lastUpdated?: string;
+    };
+    /** Step progress table */
+    stepProgress: Array<{
+        step: string;
+        name: string;
+        status: TaskStatus;
+        started?: string;
+        completed?: string;
+        notes?: string;
+    }>;
+    /** Blockers section */
+    blockers: string[];
+    /** Issues section */
+    issues: string[];
+    /** Notes section */
+    notes?: string;
+}
+
+/**
+ * Result of executing a step
+ */
+export declare interface StepResult {
+    /** Whether the step succeeded */
+    success: boolean;
+    /** Step number */
+    step: number;
+    /** Output from execution */
+    output?: string;
+    /** Error if failed */
+    error?: Error;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Artifacts produced */
+    artifacts?: string[];
+}
+
+/**
+ * RiotPlan Type Definitions
+ *
+ * Types for long-lived, stateful AI workflows (plans).
+ *
+ * A plan consists of:
+ * - A directory (the plan code/name)
+ * - A meta-prompt (prompt-of-prompts)
+ * - Numbered step files (01-STEP.md, 02-STEP.md, etc.)
+ * - Status tracking (STATUS.md)
+ * - Execution strategy (EXECUTION_PLAN.md)
+ * - Summary (SUMMARY.md)
+ * - Optional analysis directory
+ */
+/**
+ * Status of a task, phase, or step
+ */
+export declare type TaskStatus = "pending" | "in_progress" | "completed" | "failed" | "blocked" | "skipped";
+
+/**
+ * Update plan state after step completion
+ *
+ * @param plan - The plan
+ * @param stepNumber - Completed step
+ * @param result - Step result
+ * @returns Updated plan
+ *
+ * @stub Not yet implemented
+ */
+export declare function updatePlanState(_plan: unknown, _stepNumber: number, _result: unknown): never;
+
+export declare const VERSION = "0.0.1";
+
+export { }

package/dist/index.js

@@ -0,0 +1,82 @@
+const PLAN_CONVENTIONS = {
+  /** Meta-prompt file patterns */
+  metaPromptPatterns: [
+    "{code}-prompt.md",
+    "prompt-of-prompts.md",
+    "{code}.md"
+  ],
+  /** Step file pattern */
+  stepPattern: /^(\d{2})-(.+)\.md$/,
+  /** Standard files */
+  standardFiles: {
+    summary: "SUMMARY.md",
+    status: "STATUS.md",
+    executionPlan: "EXECUTION_PLAN.md",
+    readme: "README.md"
+  },
+  /** Standard directories */
+  standardDirs: {
+    plan: "plan",
+    analysis: "analysis",
+    architecture: "architecture",
+    implementation: "implementation",
+    testing: "testing"
+  },
+  /** Status emoji mapping */
+  statusEmoji: {
+    pending: "⬜",
+    in_progress: "🔄",
+    completed: "✅",
+    failed: "❌",
+    blocked: "⏸️",
+    skipped: "⏭️"
+  }
+};
+const VERSION = "0.0.1";
+async function loadPlan(_path) {
+  throw new Error(
+    "riotplan.loadPlan is not yet implemented. Coming in v0.1.0!"
+  );
+}
+async function createPlan(_config) {
+  throw new Error(
+    "riotplan.createPlan is not yet implemented. Coming in v0.1.0!"
+  );
+}
+function parseStatus(_content) {
+  throw new Error(
+    "riotplan.parseStatus is not yet implemented. Coming in v0.1.0!"
+  );
+}
+function generateStatus(_plan) {
+  throw new Error(
+    "riotplan.generateStatus is not yet implemented. Coming in v0.1.0!"
+  );
+}
+async function executeStep(_plan, _stepNumber, _context) {
+  throw new Error(
+    "riotplan.executeStep is not yet implemented. Coming in v0.1.0!"
+  );
+}
+async function resumePlan(_plan, _context) {
+  throw new Error(
+    "riotplan.resumePlan is not yet implemented. Coming in v0.1.0!"
+  );
+}
+function updatePlanState(_plan, _stepNumber, _result) {
+  throw new Error(
+    "riotplan.updatePlanState is not yet implemented. Coming in v0.1.0!"
+  );
+}
+export {
+  PLAN_CONVENTIONS,
+  VERSION,
+  createPlan,
+  executeStep,
+  generateStatus,
+  loadPlan,
+  parseStatus,
+  resumePlan,
+  updatePlanState
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/types.ts","../src/index.ts"],"sourcesContent":["/**\n * RiotPlan Type Definitions\n *\n * Types for long-lived, stateful AI workflows (plans).\n *\n * A plan consists of:\n * - A directory (the plan code/name)\n * - A meta-prompt (prompt-of-prompts)\n * - Numbered step files (01-STEP.md, 02-STEP.md, etc.)\n * - Status tracking (STATUS.md)\n * - Execution strategy (EXECUTION_PLAN.md)\n * - Summary (SUMMARY.md)\n * - Optional analysis directory\n */\n\n// ===== TASK STATUS =====\n\n/**\n * Status of a task, phase, or step\n */\nexport type TaskStatus =\n  | \"pending\" // Not started (⬜)\n  | \"in_progress\" // Currently active (🔄)\n  | \"completed\" // Done (✅)\n  | \"failed\" // Failed with error (❌)\n  | \"blocked\" // Waiting on dependency (⏸️)\n  | \"skipped\"; // Intentionally skipped (⏭️)\n\n/**\n * Priority level\n */\nexport type Priority = \"high\" | \"medium\" | \"low\";\n\n// ===== PLAN STRUCTURE =====\n\n/**\n * A single step in a plan (corresponds to a numbered file like 01-STEP.md)\n */\nexport interface PlanStep {\n  /** Step number (1, 2, 3...) */\n  number: number;\n\n  /** Step code/slug (extracted from filename, e.g., \"execution-interfaces\") */\n  code: string;\n\n  /** Full filename (e.g., \"01-execution-interfaces.md\") */\n  filename: string;\n\n  /** Human-readable title */\n  title: string;\n\n  /** Step description */\n  description?: string;\n\n  /** Current status */\n  status: TaskStatus;\n\n  /** Dependencies on other steps (by number) */\n  dependencies?: number[];\n\n  /** When this step was started */\n  startedAt?: Date;\n\n  /** When this step was completed */\n  completedAt?: Date;\n\n  /** Duration in milliseconds */\n  duration?: number;\n\n  /** Notes or issues encountered */\n  notes?: string;\n\n  /** Path to the step file */\n  filePath: string;\n}\n\n/**\n * A phase grouping multiple steps\n */\nexport interface PlanPhase {\n  /** Phase number */\n  number: number;\n\n  /** Phase name */\n  name: string;\n\n  /** Description */\n  description?: string;\n\n  /** Steps in this phase */\n  steps: number[]; // Step numbers\n\n  /** Phase status (derived from step statuses) */\n  status: TaskStatus;\n\n  /** Estimated duration */\n  estimatedDuration?: string;\n\n  /** Actual duration */\n  actualDuration?: string;\n}\n\n/**\n * Blocker preventing progress\n */\nexport interface Blocker {\n  /** Unique identifier */\n  id: string;\n\n  /** Description of the blocker */\n  description: string;\n\n  /** Severity */\n  severity: Priority;\n\n  /** Affected steps */\n  affectedSteps: number[];\n\n  /** When created */\n  createdAt: Date;\n\n  /** When resolved */\n  resolvedAt?: Date;\n\n  /** Resolution notes */\n  resolution?: string;\n}\n\n/**\n * Issue encountered during execution\n */\nexport interface Issue {\n  /** Unique identifier */\n  id: string;\n\n  /** Issue title */\n  title: string;\n\n  /** Description */\n  description: string;\n\n  /** Severity */\n  severity: Priority;\n\n  /** Related step */\n  step?: number;\n\n  /** When encountered */\n  createdAt: Date;\n\n  /** When resolved */\n  resolvedAt?: Date;\n\n  /** How it was resolved */\n  resolution?: string;\n}\n\n// ===== PLAN METADATA =====\n\n/**\n * Plan metadata from the directory and files\n */\nexport interface PlanMetadata {\n  /** Plan code (directory name, e.g., \"big-splitup\") */\n  code: string;\n\n  /** Human-readable name */\n  name: string;\n\n  /** Description from SUMMARY.md or meta-prompt */\n  description?: string;\n\n  /** Version (for tracking changes to the plan itself) */\n  version?: string;\n\n  /** Author */\n  author?: string;\n\n  /** Tags for categorization */\n  tags?: string[];\n\n  /** When the plan was created */\n  createdAt?: Date;\n\n  /** Path to the plan directory */\n  path: string;\n}\n\n// ===== PLAN FILES =====\n\n/**\n * Standard plan files\n */\nexport interface PlanFiles {\n  /** Meta-prompt file (e.g., \"big-splitup-prompt.md\" or \"prompt-of-prompts.md\") */\n  metaPrompt?: string;\n\n  /** Summary file */\n  summary?: string;\n\n  /** Status file */\n  status?: string;\n\n  /** Execution plan file */\n  executionPlan?: string;\n\n  /** README file */\n  readme?: string;\n\n  /** Step files in order */\n  steps: string[];\n\n  /** Analysis directory */\n  analysisDir?: string;\n\n  /** Other directories (architecture/, implementation/, testing/) */\n  subdirectories: string[];\n}\n\n// ===== PLAN STATE =====\n\n/**\n * Current state of plan execution\n */\nexport interface PlanState {\n  /** Overall plan status */\n  status: TaskStatus;\n\n  /** Current step being executed */\n  currentStep?: number;\n\n  /** Last completed step */\n  lastCompletedStep?: number;\n\n  /** When execution started */\n  startedAt?: Date;\n\n  /** When last updated */\n  lastUpdatedAt: Date;\n\n  /** When completed */\n  completedAt?: Date;\n\n  /** Active blockers */\n  blockers: Blocker[];\n\n  /** Issues encountered */\n  issues: Issue[];\n\n  /** Progress percentage (0-100) */\n  progress: number;\n}\n\n// ===== COMPLETE PLAN =====\n\n/**\n * Complete plan definition\n */\nexport interface Plan {\n  /** Plan metadata */\n  metadata: PlanMetadata;\n\n  /** Plan files */\n  files: PlanFiles;\n\n  /** Plan steps */\n  steps: PlanStep[];\n\n  /** Plan phases (optional grouping) */\n  phases?: PlanPhase[];\n\n  /** Current state */\n  state: PlanState;\n}\n\n// ===== EXECUTION =====\n\n/**\n * Context for plan execution\n */\nexport interface PlanContext {\n  /** Working directory */\n  workingDirectory: string;\n\n  /** The plan being executed */\n  plan: Plan;\n\n  /** Logger instance */\n  logger?: any;\n\n  /** Storage for artifacts */\n  storage?: any;\n\n  /** Environment variables */\n  env?: Record<string, string>;\n}\n\n/**\n * Result of executing a step\n */\nexport interface StepResult {\n  /** Whether the step succeeded */\n  success: boolean;\n\n  /** Step number */\n  step: number;\n\n  /** Output from execution */\n  output?: string;\n\n  /** Error if failed */\n  error?: Error;\n\n  /** Duration in milliseconds */\n  duration: number;\n\n  /** Artifacts produced */\n  artifacts?: string[];\n}\n\n/**\n * Result of executing a plan\n */\nexport interface PlanResult {\n  /** Whether the plan completed successfully */\n  success: boolean;\n\n  /** Steps that were executed */\n  executedSteps: number[];\n\n  /** Steps that succeeded */\n  completedSteps: number[];\n\n  /** Steps that failed */\n  failedSteps: number[];\n\n  /** Steps that were skipped */\n  skippedSteps: number[];\n\n  /** Total duration */\n  duration: number;\n\n  /** Final plan state */\n  finalState: PlanState;\n}\n\n// ===== SERIALIZATION =====\n\n/**\n * STATUS.md schema for parsing/generating\n */\nexport interface StatusDocument {\n  /** Document title */\n  title: string;\n\n  /** Current state summary */\n  currentState: {\n    status: TaskStatus;\n    currentStep?: string;\n    lastCompleted?: string;\n    startedAt?: string;\n    lastUpdated?: string;\n  };\n\n  /** Step progress table */\n  stepProgress: Array<{\n    step: string;\n    name: string;\n    status: TaskStatus;\n    started?: string;\n    completed?: string;\n    notes?: string;\n  }>;\n\n  /** Blockers section */\n  blockers: string[];\n\n  /** Issues section */\n  issues: string[];\n\n  /** Notes section */\n  notes?: string;\n}\n\n/**\n * EXECUTION_PLAN.md schema\n */\nexport interface ExecutionPlanDocument {\n  /** Strategy description */\n  strategy: string;\n\n  /** Prerequisites */\n  prerequisites: string[];\n\n  /** Phases with their steps */\n  phases: Array<{\n    name: string;\n    description: string;\n    steps: string[];\n  }>;\n\n  /** Quality gates */\n  qualityGates?: string[];\n\n  /** Rollback instructions */\n  rollback?: string;\n}\n\n// ===== PLAN CONVENTIONS =====\n\n/**\n * File naming conventions\n */\nexport const PLAN_CONVENTIONS = {\n    /** Meta-prompt file patterns */\n    metaPromptPatterns: [\n        \"{code}-prompt.md\",\n        \"prompt-of-prompts.md\",\n        \"{code}.md\",\n    ],\n\n    /** Step file pattern */\n    stepPattern: /^(\\d{2})-(.+)\\.md$/,\n\n    /** Standard files */\n    standardFiles: {\n        summary: \"SUMMARY.md\",\n        status: \"STATUS.md\",\n        executionPlan: \"EXECUTION_PLAN.md\",\n        readme: \"README.md\",\n    },\n\n    /** Standard directories */\n    standardDirs: {\n        plan: \"plan\",\n        analysis: \"analysis\",\n        architecture: \"architecture\",\n        implementation: \"implementation\",\n        testing: \"testing\",\n    },\n\n    /** Status emoji mapping */\n    statusEmoji: {\n        pending: \"⬜\",\n        in_progress: \"🔄\",\n        completed: \"✅\",\n        failed: \"❌\",\n        blocked: \"⏸️\",\n        skipped: \"⏭️\",\n    } as Record<TaskStatus, string>,\n} as const;\n\n","/**\n * RiotPlan - Framework for long-lived, stateful AI workflows\n *\n * A plan is a structured way to manage multi-step AI-assisted tasks that:\n * - Span multiple sessions/days\n * - Have persistent state (STATUS.md)\n * - Are organized into numbered steps\n * - Can be interrupted and resumed\n * - Track progress with checkboxes and statuses\n *\n * @example Plan directory structure:\n * ```\n * my-plan/\n * ├── my-plan-prompt.md     # Meta-prompt (prompt-of-prompts)\n * ├── SUMMARY.md            # Overview of the approach\n * ├── EXECUTION_PLAN.md     # Step-by-step strategy\n * ├── STATUS.md             # Current state (auto-updated)\n * ├── plan/                 # Step files (optional subdirectory)\n * │   ├── 01-first-step.md\n * │   ├── 02-second-step.md\n * │   └── ...\n * └── analysis/             # Analysis output (optional)\n * ```\n */\n\n// ===== EXPORTS =====\n\n// Types\nexport type {\n    TaskStatus,\n    Priority,\n    PlanStep,\n    PlanPhase,\n    Blocker,\n    Issue,\n    PlanMetadata,\n    PlanFiles,\n    PlanState,\n    Plan,\n    PlanContext,\n    StepResult,\n    PlanResult,\n    StatusDocument,\n    ExecutionPlanDocument,\n} from \"./types.js\";\n\n// Constants\nexport { PLAN_CONVENTIONS } from \"./types.js\";\n\n// Version\nexport const VERSION = \"0.0.1\";\n\n// ===== STUB IMPLEMENTATIONS =====\n// These will be implemented as the project develops\n\n/**\n * Load a plan from a directory\n *\n * @param path - Path to the plan directory\n * @returns The loaded plan\n *\n * @example\n * ```typescript\n * const plan = await loadPlan('./prompts/big-splitup');\n * console.log(plan.metadata.code); // 'big-splitup'\n * console.log(plan.steps.length);  // 11\n * ```\n *\n * @stub Not yet implemented\n */\nexport async function loadPlan(_path: string): Promise<never> {\n    throw new Error(\n        \"riotplan.loadPlan is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Create a new plan\n *\n * @param config - Plan configuration\n * @returns The created plan\n *\n * @example\n * ```typescript\n * const plan = await createPlan({\n *   code: 'my-feature',\n *   name: 'My Feature Implementation',\n *   path: './prompts/my-feature',\n *   steps: [\n *     { title: 'Setup', description: 'Initial setup' },\n *     { title: 'Implementation', description: 'Core work' },\n *     { title: 'Testing', description: 'Verify it works' },\n *   ]\n * });\n * ```\n *\n * @stub Not yet implemented\n */\nexport async function createPlan(_config: {\n  code: string;\n  name: string;\n  path: string;\n  description?: string;\n  steps?: Array<{ title: string; description?: string }>;\n}): Promise<never> {\n    throw new Error(\n        \"riotplan.createPlan is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Parse a STATUS.md file\n *\n * @param content - The STATUS.md content\n * @returns Parsed status document\n *\n * @stub Not yet implemented\n */\nexport function parseStatus(_content: string): never {\n    throw new Error(\n        \"riotplan.parseStatus is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Generate a STATUS.md file\n *\n * @param plan - The plan to generate status for\n * @returns STATUS.md content\n *\n * @stub Not yet implemented\n */\nexport function generateStatus(_plan: unknown): never {\n    throw new Error(\n        \"riotplan.generateStatus is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Execute a plan step\n *\n * @param plan - The plan\n * @param stepNumber - Step to execute\n * @param context - Execution context\n * @returns Step result\n *\n * @stub Not yet implemented\n */\nexport async function executeStep(\n    _plan: unknown,\n    _stepNumber: number,\n    _context?: unknown\n): Promise<never> {\n    throw new Error(\n        \"riotplan.executeStep is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Resume a plan from its current state\n *\n * @param plan - The plan to resume\n * @param context - Execution context\n * @returns Plan result\n *\n * @stub Not yet implemented\n */\nexport async function resumePlan(\n    _plan: unknown,\n    _context?: unknown\n): Promise<never> {\n    throw new Error(\n        \"riotplan.resumePlan is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n/**\n * Update plan state after step completion\n *\n * @param plan - The plan\n * @param stepNumber - Completed step\n * @param result - Step result\n * @returns Updated plan\n *\n * @stub Not yet implemented\n */\nexport function updatePlanState(\n    _plan: unknown,\n    _stepNumber: number,\n    _result: unknown\n): never {\n    throw new Error(\n        \"riotplan.updatePlanState is not yet implemented. Coming in v0.1.0!\"\n    );\n}\n\n"],"names":[],"mappings":"AA6ZO,MAAM,mBAAmB;AAAA;AAAA,EAE5B,oBAAoB;AAAA,IAChB;AAAA,IACA;AAAA,IACA;AAAA,EAAA;AAAA;AAAA,EAIJ,aAAa;AAAA;AAAA,EAGb,eAAe;AAAA,IACX,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,eAAe;AAAA,IACf,QAAQ;AAAA,EAAA;AAAA;AAAA,EAIZ,cAAc;AAAA,IACV,MAAM;AAAA,IACN,UAAU;AAAA,IACV,cAAc;AAAA,IACd,gBAAgB;AAAA,IAChB,SAAS;AAAA,EAAA;AAAA;AAAA,EAIb,aAAa;AAAA,IACT,SAAS;AAAA,IACT,aAAa;AAAA,IACb,WAAW;AAAA,IACX,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,SAAS;AAAA,EAAA;AAEjB;AChZO,MAAM,UAAU;AAoBvB,eAAsB,SAAS,OAA+B;AAC1D,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAwBA,eAAsB,WAAW,SAMd;AACf,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAUO,SAAS,YAAY,UAAyB;AACjD,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAUO,SAAS,eAAe,OAAuB;AAClD,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAYA,eAAsB,YAClB,OACA,aACA,UACc;AACd,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAWA,eAAsB,WAClB,OACA,UACc;AACd,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;AAYO,SAAS,gBACZ,OACA,aACA,SACK;AACL,QAAM,IAAI;AAAA,IACN;AAAA,EAAA;AAER;"}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@riotprompt/riotplan",
+  "version": "0.0.2",
+  "description": "Framework for long-lived, stateful AI workflows (plans)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "vite build",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "plan",
+    "workflow",
+    "ai",
+    "stateful",
+    "llm",
+    "prompts",
+    "execution"
+  ],
+  "author": "Tim O'Brien <tobrien@discursive.com>",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kjerneverk/riotplan"
+  },
+  "dependencies": {
+    "glob": "^11.0.3",
+    "js-yaml": "^4.1.1",
+    "marked": "^16.0.0"
+  },
+  "peerDependencies": {
+    "@riotprompt/agentic": "^0.0.1",
+    "@riotprompt/execution": "^0.0.1",
+    "@riotprompt/riotprompt": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@riotprompt/agentic": {
+      "optional": true
+    },
+    "@riotprompt/execution": {
+      "optional": true
+    },
+    "@riotprompt/riotprompt": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.28.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.15.30",
+    "@typescript-eslint/eslint-plugin": "^8.34.0",
+    "@typescript-eslint/parser": "^8.34.0",
+    "eslint": "^9.28.0",
+    "eslint-plugin-import": "^2.31.0",
+    "globals": "^16.2.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.0.4",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
+  }
+}