@dexto/tools-plan 1.5.7

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Plan Types and Schemas
+ *
+ * Defines the structure of plans and their metadata.
+ */
+import { z } from 'zod';
+/**
+ * Plan status values
+ */
+export declare const PlanStatusSchema: z.ZodEnum<["draft", "approved", "in_progress", "completed", "abandoned"]>;
+export type PlanStatus = z.infer<typeof PlanStatusSchema>;
+/**
+ * Plan metadata stored alongside the plan content
+ */
+export declare const PlanMetaSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    status: z.ZodDefault<z.ZodEnum<["draft", "approved", "in_progress", "completed", "abandoned"]>>;
+    title: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    status: "draft" | "approved" | "in_progress" | "completed" | "abandoned";
+    createdAt: number;
+    updatedAt: number;
+    title?: string | undefined;
+}, {
+    sessionId: string;
+    createdAt: number;
+    updatedAt: number;
+    status?: "draft" | "approved" | "in_progress" | "completed" | "abandoned" | undefined;
+    title?: string | undefined;
+}>;
+export type PlanMeta = z.infer<typeof PlanMetaSchema>;
+/**
+ * Complete plan with content and metadata
+ */
+export interface Plan {
+    content: string;
+    meta: PlanMeta;
+}
+/**
+ * Options for the plan service
+ */
+export interface PlanServiceOptions {
+    /** Base directory for plan storage */
+    basePath: string;
+}
+/**
+ * Result of a plan update operation
+ */
+export interface PlanUpdateResult {
+    oldContent: string;
+    newContent: string;
+    meta: PlanMeta;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,gBAAgB,2EAM3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;EAMzB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,IAAI;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,QAAQ,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1,26 @@
+/**
+ * Plan Types and Schemas
+ *
+ * Defines the structure of plans and their metadata.
+ */
+import { z } from 'zod';
+/**
+ * Plan status values
+ */
+export const PlanStatusSchema = z.enum([
+    'draft',
+    'approved',
+    'in_progress',
+    'completed',
+    'abandoned',
+]);
+/**
+ * Plan metadata stored alongside the plan content
+ */
+export const PlanMetaSchema = z.object({
+    sessionId: z.string().describe('Session ID this plan belongs to'),
+    status: PlanStatusSchema.default('draft').describe('Current plan status'),
+    title: z.string().optional().describe('Plan title'),
+    createdAt: z.number().describe('Unix timestamp when plan was created'),
+    updatedAt: z.number().describe('Unix timestamp when plan was last updated'),
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dexto/tools-plan",
+  "version": "1.5.7",
+  "description": "Implementation planning tools with session-linked plans",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    ".dexto-plugin",
+    "skills"
+  ],
+  "dependencies": {
+    "diff": "^7.0.0",
+    "zod": "^3.24.1",
+    "@dexto/core": "1.5.7"
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.0",
+    "@types/node": "^22.10.5",
+    "dotenv": "^16.4.7",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "author": "Dexto",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/skills/plan/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: plan
+description: Enter planning mode to create and manage implementation plans
+user-invocable: true
+---
+
+# Planning Mode - PLAN FIRST, THEN IMPLEMENT
+
+**CRITICAL**: You are in planning mode. You MUST create and get approval for a plan BEFORE writing any code or making any changes.
+
+## MANDATORY WORKFLOW
+
+**DO NOT skip these steps. DO NOT start implementing until the plan is approved.**
+
+1. **Research first** (if needed): Use the explore agent or read relevant files to understand the codebase
+2. **Check for existing plan**: Use `plan_read` to see if a plan exists
+3. **Create/update plan**: Use `plan_create` or `plan_update` to define your approach
+4. **Request review**: Use `plan_review` to get user approval
+5. **WAIT for approval**: Only proceed to implementation after user approves
+6. **Implement**: Execute the approved plan, updating checkboxes as you go
+
+## Research Phase
+
+Before creating your plan, you should understand the codebase:
+
+- **Use the explore agent** (spawn_agent with subagent_type="Explore") to search for relevant code, patterns, and existing implementations
+- **Read key files** to understand the current architecture
+- **Identify dependencies** and files that will need changes
+
+This research informs your plan and prevents wasted effort from incorrect assumptions.
+
+## Available Tools
+
+- **plan_create**: Create a new plan (REQUIRED before any implementation)
+- **plan_read**: Read the current plan
+- **plan_update**: Update the existing plan (shows diff preview)
+- **plan_review**: Request user review - returns approve/iterate/reject with feedback
+
+## WHAT YOU MUST DO NOW
+
+1. **Research**: Use the explore agent or read files to understand the relevant parts of the codebase
+2. **Check plan**: Use `plan_read` to check if a plan already exists
+3. **Create plan**: Use `plan_create` to create a comprehensive plan based on your research
+4. **Get approval**: Use `plan_review` to request user approval
+5. **STOP and WAIT** - do not write any code until the user approves via plan_review
+
+## Plan Structure
+
+```markdown
+# {Title}
+
+## Objective
+{Clear statement of what we're building/fixing}
+
+## Steps
+
+### 1. {Step Name}
+- [ ] {Task description}
+- [ ] {Task description}
+Files: `path/to/file.ts`, `path/to/other.ts`
+
+### 2. {Step Name}
+- [ ] {Task description}
+Files: `path/to/file.ts`
+
+## Considerations
+- {Edge cases to handle}
+- {Error scenarios}
+
+## Success Criteria
+- {How we know we're done}
+```
+
+## Guidelines
+
+- **Break down complex tasks** into clear, sequential steps
+- **Include specific file paths** that will be created or modified
+- **Note dependencies** between steps
+- **Keep plans concise** but complete
+
+## Handling Review Responses
+
+After calling `plan_review`, handle the response:
+
+- **approve**: User approved - proceed with implementation
+- **iterate**: User wants changes - update the plan based on feedback, then call `plan_review` again
+- **reject**: User rejected - ask what they want instead
+
+## DO NOT
+
+- ❌ Start writing code before creating a plan
+- ❌ Skip the plan_review step
+- ❌ Assume approval - wait for explicit user response
+- ❌ Make changes outside the approved plan without updating it first
+
+---
+
+**START NOW**:
+1. Research the codebase using the explore agent if needed
+2. Use `plan_read` to check for an existing plan
+3. Use `plan_create` to create your plan
+4. Use `plan_review` to get approval before any implementation