@quinteroac/agents-coding-toolkit 0.1.0-preview → 0.1.1-preview.0

package/README.md

@@ -73,7 +73,7 @@ nerds-vst is a package that provides:
   |-------|----------|
   | **Iteration** | `bun nvst start iteration` — Start or advance to the next iteration (archives current, resets state). |
   | **Define** | `bun nvst define requirement` → `bun nvst refine requirement` (optional) → `bun nvst approve requirement` → `bun nvst create prd` |
-  | **Prototype** | `bun nvst create project-context` → `bun nvst approve project-context` → `bun nvst create prototype` → `bun nvst define test-plan` → `bun nvst approve test-plan` → `bun nvst execute test-plan` → `bun nvst execute automated-fix` / `bun nvst execute manual-fix` → `bun nvst approve prototype` |
+  | **Prototype** | `bun nvst create project-context` → `bun nvst approve project-context` → `bun nvst create prototype` → `bun nvst define test-plan` → `bun nvst approve test-plan` → `bun nvst execute test-plan` → `bun nvst execute automated-fix` / `bun nvst execute manual-fix` → when all tests pass, prototype is done and Refactor can begin |
   | **Refactor** | `bun nvst define refactor-plan` → `bun nvst approve refactor-plan` → `bun nvst create prd --refactor` → `bun nvst execute refactor` → update PROJECT_CONTEXT, CHANGELOG → then `bun nvst start iteration` for next iteration |
 
 

package/package.json

@@ -4,12 +4,14 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "version": "0.1.0-preview",
+  "version": "0.1.1-preview.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/quinteroac/nerds-vibecoding-survivor-toolkit.git"
+    "url": "git+https://github.com/quinteroac/nerds-vibecoding-survivor-toolkit.git"
+  },
+  "bin": {
+    "nvst": "src/cli.ts"
   },
-  "bin": { "nvst": "src/cli.ts" },
   "files": [
     "src",
     "scaffold",
@@ -19,9 +21,16 @@
     "tsconfig.json"
   ],
   "scripts": {
+    "test": "bun test src tests schemas",
     "package": "npm pack",
+    "bump": "npm version",
+    "bump:patch": "npm version patch",
+    "bump:minor": "npm version minor",
+    "bump:major": "npm version major",
+    "bump:preview": "npm version prerelease",
     "validate:state": "bun run scaffold/schemas/tmpl_validate-state.ts",
-    "validate:progress": "bun run scaffold/schemas/tmpl_validate-progress.ts"
+    "validate:progress": "bun run scaffold/schemas/tmpl_validate-progress.ts",
+    "sync-check": "bun run scripts/sync-check.ts"
   },
   "dependencies": {
     "zod": "^3.23.8"

package/scaffold/.agents/skills/execute-refactor-item/tmpl_SKILL.md

@@ -0,0 +1,59 @@
+---
+name: execute-refactor-item
+description: "Applies a single approved refactor item (RI-NNN) to the codebase. Invoked by: bun nvst execute refactor."
+user-invocable: false
+---
+
+# Execute Refactor Item
+
+Apply the provided refactor item to the codebase, following the project's conventions and architecture.
+
+---
+
+## The Job
+
+1. Read the **refactor item** (`id`, `title`, `description`, `rationale`) carefully.
+2. Review the **project context** to understand conventions, tech stack, and module structure.
+3. Plan the change: identify which files to create or modify and how the change fits into the existing architecture.
+4. Apply the refactor:
+   - Make the changes described in the item's `description`.
+   - Ensure the code compiles / type-checks without errors after the change.
+   - Run any quality checks defined in the project context and fix failures before finishing.
+5. Do **not** commit — the calling command manages git operations.
+
+---
+
+## Inputs
+
+| Source | Used for |
+|--------|----------|
+| `refactor_item_id` (context variable) | The refactor item identifier (e.g. `RI-001`) |
+| `refactor_item_title` (context variable) | Short title of the refactor item |
+| `refactor_item_description` (context variable) | Detailed description of the change to apply |
+| `refactor_item_rationale` (context variable) | Why this refactor is needed |
+| `iteration` (context variable) | Current iteration number for context |
+| `.agents/PROJECT_CONTEXT.md` | Documented conventions, architecture, and standards to follow |
+
+---
+
+## Rules
+
+- **One item at a time.** Apply only the refactor item provided — do not make unrelated changes.
+- **Follow conventions exactly.** Use the naming, formatting, error handling, and module organisation patterns from the project context.
+- **No new dependencies** unless the refactor item explicitly requires them.
+- **Do not modify state files.** Do not touch `.agents/state.json` or progress files — the calling command manages those.
+- **Do not commit.** The calling command handles git operations.
+- **Keep changes minimal.** Only modify files necessary to apply the refactor item.
+
+---
+
+## Checklist
+
+Before finishing:
+
+- [ ] Refactor item changes are applied as described
+- [ ] Code compiles / type-checks without errors
+- [ ] Quality checks pass
+- [ ] No unrelated changes were made
+- [ ] No state files were modified
+- [ ] No git commits were made

package/scaffold/.agents/skills/plan-refactor/tmpl_SKILL.md

@@ -1,19 +1,99 @@
-# plan-refactor (scaffold)
+---
+name: plan-refactor
+description: "Evaluates the prototype and produces an ordered refactor plan. Triggered by: bun nvst define refactor-plan."
+user-invocable: true
+---
 
-<!-- TODO: Complete. All content in English. -->
+# Evaluate and Plan Refactor
 
-## Objective
+This skill runs in two parts within a single session. **Do NOT implement code.** Only produce documents.
 
-TBD — From evaluation report: identify quick wins and critical refactorings, ask user about refactorings that need a decision, produce ordered plan.
+## Part 1: Evaluate the Prototype
 
-## Inputs
+Evaluate the current prototype before planning refactorings.
 
-TBD — `it_<iteration>_evaluation-report.md`.
+### Evaluation Inputs
 
-## Outputs
+| Source | Used for |
+|--------|----------|
+| `.agents/PROJECT_CONTEXT.md` | Documented conventions, architecture, and standards to validate against |
+| `.agents/TECHNICAL_DEBT.md` | Existing technical debt (if present) |
+| `.agents/flow/it_{current_iteration}_PRD.json` | Implemented scope for this iteration |
+| Prototype codebase | Actual structure, patterns, and quality |
 
-TBD — `it_<iteration>_refactor_plan.md`.
+### Evaluation Output
+
+Write `it_{current_iteration}_evaluation-report.md` to `.agents/flow/` with this structure:
+
+```markdown
+# Evaluation Report — Iteration {current_iteration}
+
+## Strengths
+- What works well in the current prototype
+
+## Technical Debt
+- Known debt items, with brief impact/effort notes
+
+## Violations of PROJECT_CONTEXT.md
+- Conventions, architecture, or standards not followed
+
+## Recommendations
+Each item: description, impact, urgency, effort, scope. Optional numeric score for ordering.
+```
+
+Complete Part 1 before starting Part 2. The evaluation report is the input for the refactor plan.
+
+---
+
+## Part 2: Define the Refactor Plan
+
+From the evaluation report you just produced, define an ordered refactor plan.
+
+### Plan Inputs
+
+| Source | Used for |
+|--------|----------|
+| `it_{current_iteration}_evaluation-report.md` | Issues, technical debt, and recommendations to prioritise |
+| User (interactive) | Decisions on trade-offs or approaches that need clarification |
+
+### Plan Output
+
+Write `it_{current_iteration}_refactor-plan.md` to `.agents/flow/` with this structure:
+
+```markdown
+# Refactor Plan — Iteration {current_iteration}
+
+## Refactor Items
+
+### RI-001: <Title>
+
+**Description:** One or two sentences describing what needs to change and why it is a problem.
+
+**Rationale:** Why this item is prioritised at this position — impact, urgency, or risk reduction.
+
+### RI-002: <Title>
+
+**Description:** ...
+
+**Rationale:** ...
+```
+
+### Plan Instructions
+
+1. Read the evaluation report in full before writing the refactor plan.
+2. Identify quick wins (low effort, high impact) and critical refactorings (high urgency or high risk).
+3. For items that require a user decision (e.g. trade-offs between approaches), ask the user before committing to an entry.
+4. Order items by priority: critical blockers first, quick wins second, long-term improvements last.
+5. Assign each item a unique id in `RI-NNN` format (e.g. `RI-001`, `RI-002`).
+6. Write the refactor plan file.
+
+---
 
 ## Checklist
 
-TBD
+- [ ] Output is in English
+- [ ] Part 1: `it_{current_iteration}_evaluation-report.md` written to `.agents/flow/`
+- [ ] Part 2: `it_{current_iteration}_refactor-plan.md` written to `.agents/flow/`
+- [ ] Each refactor item has a unique `RI-NNN` id, `**Description:**`, and `**Rationale:**`
+- [ ] Refactor items are ordered by priority
+- [ ] State files are not modified by this skill

package/scaffold/.agents/skills/refine-refactor-plan/tmpl_SKILL.md

@@ -0,0 +1,30 @@
+---
+name: refine-refactor-plan
+description: "Refines an existing refactor plan based on user feedback or adversarial challenge mode. Triggered by: bun nvst refine refactor-plan."
+user-invocable: true
+---
+
+# Refine Refactor Plan
+
+Update `it_{current_iteration}_refactor-plan.md` in place. The file already exists and is provided in context.
+
+**Do NOT implement code. Only revise the refactor plan document.**
+
+> **Two modes available — determined by the `mode` context variable:**
+> - **Editor mode** (default): apply user-requested updates to the plan.
+> - **Challenger mode** (`mode = "challenger"`): challenge sequencing, risk handling, and testability before applying edits.
+
+## Inputs
+
+| Source | Used for |
+|--------|----------|
+| `refactor_plan_file` | Current plan file name |
+| `refactor_plan_content` | Existing plan content |
+| User responses | Clarifications and approval of proposed edits |
+
+## Checklist
+
+- [ ] Output remains in English
+- [ ] Accepted changes are applied to the existing refactor plan file
+- [ ] Same output file path is preserved (refine in place, do not write a new file)
+- [ ] State files are not modified by this skill

package/scaffold/.agents/tmpl_state_rules.md

@@ -20,7 +20,6 @@ Each command must validate the relevant fields of `state.json` before running. I
 | `bun execute test-plan` | TBD | TBD |
 | `bun execute automated-fix` | TBD | TBD |
 | `bun execute manual-fix` | TBD | TBD |
-| `bun approve prototype` | TBD | TBD |
 | `bun define refactor-plan` | TBD | TBD |
 | `bun refine refactor-plan` | TBD | TBD |
 | `bun approve refactor-plan` | TBD | TBD |

package/scaffold/schemas/tmpl_refactor-execution-progress.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+const RefactorExecutionEntrySchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.enum(["pending", "in_progress", "completed", "failed"]),
+  attempt_count: z.number().int(),
+  last_agent_exit_code: z.number().int().nullable(),
+  updated_at: z.string(),
+});
+
+export const RefactorExecutionProgressSchema = z.object({
+  entries: z.array(RefactorExecutionEntrySchema),
+});
+
+export type RefactorExecutionProgress = z.infer<typeof RefactorExecutionProgressSchema>;

package/scaffold/schemas/tmpl_refactor-prd.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+const RefactorItemSchema = z.object({
+  id: z.string().regex(/^RI-\d{3}$/),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  rationale: z.string().min(1),
+});
+
+export const RefactorPrdSchema = z.object({
+  refactorItems: z.array(RefactorItemSchema).min(1),
+});
+
+export type RefactorPrd = z.infer<typeof RefactorPrdSchema>;

package/scaffold/schemas/tmpl_state.ts

@@ -68,6 +68,7 @@ const historyEntry = z.object({
 export const StateSchema = z.object({
   current_iteration: iterationId,
   current_phase: phase,
+  flow_guardrail: z.enum(["strict", "relaxed"]).optional(),
   phases: z.object({
     define: definePhase,
     prototype: prototypePhase,

package/schemas/refactor-execution-progress.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+const RefactorExecutionEntrySchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.enum(["pending", "in_progress", "completed", "failed"]),
+  attempt_count: z.number().int(),
+  last_agent_exit_code: z.number().int().nullable(),
+  updated_at: z.string(),
+});
+
+export const RefactorExecutionProgressSchema = z.object({
+  entries: z.array(RefactorExecutionEntrySchema),
+});
+
+export type RefactorExecutionProgress = z.infer<typeof RefactorExecutionProgressSchema>;

package/schemas/refactor-prd.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+const RefactorItemSchema = z.object({
+  id: z.string().regex(/^RI-\d{3}$/),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  rationale: z.string().min(1),
+});
+
+export const RefactorPrdSchema = z.object({
+  refactorItems: z.array(RefactorItemSchema).min(1),
+});
+
+export type RefactorPrd = z.infer<typeof RefactorPrdSchema>;

package/schemas/state.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test";
+
+import { StateSchema as ScaffoldStateSchema } from "../scaffold/schemas/tmpl_state";
+import { StateSchema as WorkingCopyStateSchema } from "./state";
+
+function makeValidState(): Record<string, unknown> {
+  return {
+    current_iteration: "000001",
+    current_phase: "define",
+    phases: {
+      define: {
+        requirement_definition: { status: "pending", file: null },
+        prd_generation: { status: "pending", file: null },
+      },
+      prototype: {
+        project_context: { status: "pending", file: null },
+        test_plan: { status: "pending", file: null },
+        tp_generation: { status: "pending", file: null },
+        prototype_build: { status: "pending", file: null },
+        test_execution: { status: "pending", file: null },
+        prototype_approved: false,
+      },
+      refactor: {
+        evaluation_report: { status: "pending", file: null },
+        refactor_plan: { status: "pending", file: null },
+        refactor_execution: { status: "pending", file: null },
+        changelog: { status: "pending", file: null },
+      },
+    },
+    last_updated: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+describe("US-003 state schema parity", () => {
+  test("US-003-AC01/AC02/AC05: both schemas accept state without flow_guardrail", () => {
+    const input = makeValidState();
+
+    expect(ScaffoldStateSchema.safeParse(input).success).toBe(true);
+    expect(WorkingCopyStateSchema.safeParse(input).success).toBe(true);
+  });
+
+  test("US-003-AC01/AC02: both schemas accept flow_guardrail='strict' and 'relaxed'", () => {
+    const strictInput = { ...makeValidState(), flow_guardrail: "strict" };
+    const relaxedInput = { ...makeValidState(), flow_guardrail: "relaxed" };
+
+    expect(ScaffoldStateSchema.safeParse(strictInput).success).toBe(true);
+    expect(ScaffoldStateSchema.safeParse(relaxedInput).success).toBe(true);
+    expect(WorkingCopyStateSchema.safeParse(strictInput).success).toBe(true);
+    expect(WorkingCopyStateSchema.safeParse(relaxedInput).success).toBe(true);
+  });
+
+  test("US-003-AC01/AC02: both schemas reject non-enum flow_guardrail", () => {
+    const invalidInput = { ...makeValidState(), flow_guardrail: "lenient" };
+
+    expect(ScaffoldStateSchema.safeParse(invalidInput).success).toBe(false);
+    expect(WorkingCopyStateSchema.safeParse(invalidInput).success).toBe(false);
+  });
+});

package/schemas/state.ts

@@ -68,6 +68,7 @@ const historyEntry = z.object({
 export const StateSchema = z.object({
   current_iteration: iterationId,
   current_phase: phase,
+  flow_guardrail: z.enum(["strict", "relaxed"]).optional(),
   phases: z.object({
     define: definePhase,
     prototype: prototypePhase,

package/schemas/test-plan.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { TestPlanSchema } from "./test-plan";
+import { TestPlanSchema } from "../scaffold/schemas/tmpl_test-plan";
 
 describe("TestPlanSchema", () => {
   test("accepts enhanced test plan metadata structure", () => {

package/src/cli.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+describe("US-005: execute refactor CLI routing and help text", () => {
+  // AC01: cli.ts routes `execute refactor` to runExecuteRefactor handler
+  test("cli.ts routes execute refactor subcommand to runExecuteRefactor", async () => {
+    const source = await readFile(join(import.meta.dir, "cli.ts"), "utf8");
+    expect(source).toContain('import { runExecuteRefactor } from "./commands/execute-refactor"');
+    expect(source).toContain('if (subcommand === "refactor")');
+    expect(source).toContain("await runExecuteRefactor({ provider, force })");
+  });
+
+  // AC02: printUsage includes `execute refactor --agent <provider>` with a one-line description
+  test("printUsage includes execute refactor --agent <provider> with one-line description", async () => {
+    const source = await readFile(join(import.meta.dir, "cli.ts"), "utf8");
+    expect(source).toContain("execute refactor --agent <provider>");
+    expect(source).toContain("Execute approved refactor items via agent in order");
+  });
+
+  // AC03: Unknown options after --agent <provider> cause clear error and exit code 1
+  test("unknown options after --agent <provider> cause clear error message and exit code 1", async () => {
+    const cliPath = join(import.meta.dir, "cli.ts");
+    const proc = Bun.spawn(
+      ["bun", cliPath, "execute", "refactor", "--agent", "claude", "--unknown-flag"],
+      {
+        stdout: "pipe",
+        stderr: "pipe",
+      },
+    );
+    const exitCode = await proc.exited;
+    const stderrText = await new Response(proc.stderr).text();
+
+    expect(exitCode).toBe(1);
+    expect(stderrText).toContain("Unknown option(s) for execute refactor");
+    expect(stderrText).toContain("--unknown-flag");
+  });
+
+  // AC03: Multiple unknown options after --agent <provider> are all reported
+  test("multiple unknown options after --agent <provider> are all listed in error message", async () => {
+    const cliPath = join(import.meta.dir, "cli.ts");
+    const proc = Bun.spawn(
+      ["bun", cliPath, "execute", "refactor", "--agent", "claude", "--foo", "--bar"],
+      {
+        stdout: "pipe",
+        stderr: "pipe",
+      },
+    );
+    const exitCode = await proc.exited;
+    const stderrText = await new Response(proc.stderr).text();
+
+    expect(exitCode).toBe(1);
+    expect(stderrText).toContain("Unknown option(s) for execute refactor");
+    expect(stderrText).toContain("--foo");
+    expect(stderrText).toContain("--bar");
+  });
+});