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

package/README.md

@@ -26,15 +26,10 @@ nerds-vst is a package that provides:
 
   ```
   AGENTS.md
-  iteration_close_checklist.md
-  ralph_loop.md
-  providers.md
   .agents/
     PROJECT_CONTEXT.md
-    state.json
     state_rules.md
-    scripts/
-      ralph.ts
+    state.example.json
     skills/
       create-pr-document/SKILL.md
       refine-pr-document/SKILL.md
@@ -49,21 +44,40 @@ nerds-vst is a package that provides:
       evaluate/SKILL.md
       plan-refactor/SKILL.md
       refactor-prd/SKILL.md
+      refine-refactor-plan/SKILL.md
+      execute-refactor-item/SKILL.md
+      automated-fix/SKILL.md
       debug/SKILL.md
     flow/
-      README.md
+      it_000001_progress.example.json
       archived/
-  docs/templates/
-    CHANGELOG.md
-    TECHNICAL_DEBT.md
+  docs/
+    nvst-flow/
+      COMMANDS.md
+      QUICK_USE.md
+      templates/
+        CHANGELOG.md
+        TECHNICAL_DEBT.md
+        it_000001_product-requirement-document.md
+        it_000001_test-plan.md
+        it_000001_evaluation-report.md
+        it_000001_refactor_plan.md
+    PLACEHOLDER.md
   schemas/
     state.ts
+    prd.ts
     progress.ts
+    test-plan.ts
+    issues.ts
+    prototype-progress.ts
+    test-execution-progress.ts
+    refactor-prd.ts
+    refactor-execution-progress.ts
     validate-state.ts
     validate-progress.ts
   ```
 
-  Template files in this repository live under [`scaffold/`](scaffold/) with a `tmpl_` prefix (e.g. `tmpl_AGENTS.md`, `tmpl_ralph_loop.md`); `bun nvst init` copies them into the target project and writes them without the prefix to avoid naming conflicts when the toolkit is integrated elsewhere.
+  Template files in this repository live under [`scaffold/`](scaffold/) with a `tmpl_` prefix (e.g. `tmpl_AGENTS.md`, `tmpl_state.ts`); `bun nvst init` copies them into the target project and writes them without the prefix to avoid naming conflicts when the toolkit is integrated elsewhere. The `state.json` file is created and managed by the toolkit at runtime.
 
 - **Command-line tool** — Sends instructions to your chosen agent provider (Claude, Codex, Gemini, etc.) so it follows the framework. Commands drive the Define → Prototype → Refactor flow and keep state in sync, giving you a single way to run the process regardless of which agent you use.
 
@@ -73,8 +87,8 @@ 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` → 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 |
+  | **Prototype** | `bun nvst create project-context` → `bun nvst approve project-context` → `bun nvst create prototype` → `bun nvst define test-plan` → `bun nvst refine test-plan` (optional) → `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 refine refactor-plan` (optional) → `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 |
 
 
 ## Installation
@@ -92,7 +106,7 @@ Install from a local directory or a packed tarball:
 bun add /path/to/nerds-vibecoding-survivor-toolkit
 
 # Or from a packed .tgz (run `bun run package` first)
-bun add ./quinteroac-agents-coding-toolkit-0.1.0.tgz
+bun add ./quinteroac-agents-coding-toolkit-0.1.1-preview.0.tgz
 ```
 
 ### From npm
@@ -124,4 +138,4 @@ Acknowledgements and credits will be added after the initial release.
 ## References
 
 - [process_design.md](process_design.md) — Full process specification.
-- [scaffold/.agents/flow/tmpl_README.md](scaffold/.agents/flow/tmpl_README.md) — Flow directory and naming conventions (scaffold template).
+- [docs/nvst-flow/](docs/nvst-flow/) — Command reference and quick usage (scaffold provides `COMMANDS.md` and `QUICK_USE.md`).

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org",
     "access": "public"
   },
-  "version": "0.1.1-preview.0",
+  "version": "0.2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/quinteroac/nerds-vibecoding-survivor-toolkit.git"
@@ -22,6 +22,7 @@
   ],
   "scripts": {
     "test": "bun test src tests schemas",
+    "typecheck": "bun tsc --noEmit",
     "package": "npm pack",
     "bump": "npm version",
     "bump:patch": "npm version patch",

package/scaffold/.agents/flow/tmpl_it_000001_progress.example.json

@@ -0,0 +1,20 @@
+{
+  "entries": [
+    {
+      "use_case_id": "US-001",
+      "timestamp": "2026-02-18T12:00:00Z",
+      "implementation": {
+        "status": "pending",
+        "summary_of_actions": "",
+        "learnings": ""
+      },
+      "tests": [
+        {
+          "id": "TC-001",
+          "description": "Example test case",
+          "status": "pending"
+        }
+      ]
+    }
+  ]
+}

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

@@ -27,11 +27,11 @@ Apply the provided refactor item to the codebase, following the project's conven
 
 | 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 |
+| `current_iteration` (context variable) | Current iteration number for context |
+| `item_id` (context variable) | The refactor item identifier (e.g. `RI-001`) |
+| `item_title` (context variable) | Short title of the refactor item |
+| `item_description` (context variable) | Detailed description of the change to apply |
+| `item_rationale` (context variable) | Why this refactor is needed |
 | `.agents/PROJECT_CONTEXT.md` | Documented conventions, architecture, and standards to follow |
 
 ---

package/scaffold/schemas/tmpl_prototype-progress.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+const PrototypeProgressEntrySchema = z.object({
+  use_case_id: z.string(),
+  status: z.enum(["pending", "failed", "completed"]),
+  attempt_count: z.number().int().nonnegative(),
+  last_agent_exit_code: z.number().int().nullable(),
+  quality_checks: z.array(
+    z.object({
+      command: z.string(),
+      exit_code: z.number().int(),
+    }),
+  ),
+  last_error_summary: z.string(),
+  updated_at: z.string(),
+});
+
+export const PrototypeProgressSchema = z.object({
+  entries: z.array(PrototypeProgressEntrySchema),
+});
+
+export type PrototypeProgress = z.infer<typeof PrototypeProgressSchema>;

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

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+const TestExecutionProgressEntrySchema = z.object({
+  id: z.string(),
+  type: z.enum(["automated", "exploratory_manual"]),
+  status: z.enum(["pending", "in_progress", "passed", "failed"]),
+  attempt_count: z.number().int().nonnegative(),
+  last_agent_exit_code: z.number().int().nullable(),
+  last_error_summary: z.string(),
+  updated_at: z.string(),
+});
+
+export const TestExecutionProgressSchema = z.object({
+  entries: z.array(TestExecutionProgressEntrySchema),
+});
+
+export type TestExecutionProgress = z.infer<typeof TestExecutionProgressSchema>;

package/schemas/issues.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+
+const IssueSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: z.string(),
+  status: z.enum(["open", "fixed", "retry", "manual-fix"]),
+});
+
+export const IssuesSchema = z.array(IssueSchema).refine(
+  (issues) => {
+    const ids = issues.map((i) => i.id);
+    return new Set(ids).size === ids.length;
+  },
+  { message: "Issue IDs must be unique" },
+);
+
+export type Issue = z.infer<typeof IssueSchema>;
+export type Issues = z.infer<typeof IssuesSchema>;

package/schemas/prototype-progress.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+const PrototypeProgressEntrySchema = z.object({
+  use_case_id: z.string(),
+  status: z.enum(["pending", "failed", "completed"]),
+  attempt_count: z.number().int().nonnegative(),
+  last_agent_exit_code: z.number().int().nullable(),
+  quality_checks: z.array(
+    z.object({
+      command: z.string(),
+      exit_code: z.number().int(),
+    }),
+  ),
+  last_error_summary: z.string(),
+  updated_at: z.string(),
+});
+
+export const PrototypeProgressSchema = z.object({
+  entries: z.array(PrototypeProgressEntrySchema),
+});
+
+export type PrototypeProgress = z.infer<typeof PrototypeProgressSchema>;

package/schemas/test-execution-progress.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+const TestExecutionProgressEntrySchema = z.object({
+  id: z.string(),
+  type: z.enum(["automated", "exploratory_manual"]),
+  status: z.enum(["pending", "in_progress", "passed", "failed"]),
+  attempt_count: z.number().int().nonnegative(),
+  last_agent_exit_code: z.number().int().nullable(),
+  last_error_summary: z.string(),
+  updated_at: z.string(),
+});
+
+export const TestExecutionProgressSchema = z.object({
+  entries: z.array(TestExecutionProgressEntrySchema),
+});
+
+export type TestExecutionProgress = z.infer<typeof TestExecutionProgressSchema>;

package/schemas/validate-progress.ts

@@ -1,4 +1,4 @@
-import { ProgressSchema } from "./tmpl_progress.ts";
+import { ProgressSchema } from "./tmpl_progress";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 

package/schemas/validate-state.ts

@@ -1,4 +1,4 @@
-import { StateSchema } from "./tmpl_state.ts";
+import { StateSchema } from "./tmpl_state";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 

package/src/cli.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env bun
 
 import { join } from "node:path";
-import { parseAgentArg } from "./agent";
+import { parseAgentArg, parseProvider, type AgentProvider } from "./agent";
 import { GuardrailAbortError } from "./guardrail";
 import { runApproveProjectContext } from "./commands/approve-project-context";
+import { runApprovePrototype } from "./commands/approve-prototype";
 import { runApproveRefactorPlan } from "./commands/approve-refactor-plan";
 import { runApproveRequirement } from "./commands/approve-requirement";
 import { runApproveTestPlan } from "./commands/approve-test-plan";
@@ -18,6 +19,7 @@ import { runExecuteAutomatedFix } from "./commands/execute-automated-fix";
 import { runExecuteManualFix } from "./commands/execute-manual-fix";
 import { runExecuteRefactor } from "./commands/execute-refactor";
 import { runExecuteTestPlan } from "./commands/execute-test-plan";
+import { runFlow } from "./commands/flow";
 import { runInit } from "./commands/init";
 import { runRefineProjectContext } from "./commands/refine-project-context";
 import { runRefineRefactorPlan } from "./commands/refine-refactor-plan";
@@ -89,6 +91,21 @@ function parseForce(args: string[]): { force: boolean; remainingArgs: string[] }
   };
 }
 
+function parseOptionalAgentArg(args: string[]): {
+  provider: AgentProvider | undefined;
+  remainingArgs: string[];
+} {
+  const { value, remainingArgs } = extractFlagValue(args, "--agent");
+  if (value === null) {
+    return { provider: undefined, remainingArgs };
+  }
+
+  return {
+    provider: parseProvider(value),
+    remainingArgs,
+  };
+}
+
 function printUsage() {
   console.log(`Usage: nvst <command> [options]
 
@@ -101,6 +118,8 @@ Commands:
                      Generate test plan document for current iteration
   create prototype --agent <provider> [--iterations <N>] [--retry-on-fail <N>] [--stop-on-critical]
                      Initialize prototype build for current iteration
+  flow [--agent <provider>] [--force]
+                     Run the next pending flow step(s) until an approval gate or completion
   create issue --agent <provider>
                      Create issues interactively via agent
   create issue --test-execution-report
@@ -109,6 +128,8 @@ Commands:
                      Mark project context as approved
   approve test-plan
                      Mark test plan as approved and generate structured TP JSON
+  approve prototype
+                     Stage and commit all pending changes for current iteration
   approve refactor-plan
                      Mark refactor plan as approved and generate structured refactor PRD JSON
   refine project-context --agent <provider> [--challenge]
@@ -211,6 +232,26 @@ async function main() {
     return;
   }
 
+  if (command === "flow") {
+    try {
+      const { provider, remainingArgs: postAgentArgs } = parseOptionalAgentArg(args);
+      const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+      if (postForceArgs.length > 0) {
+        console.error(`Unknown option(s) for flow: ${postForceArgs.join(" ")}`);
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+      await runFlow({ provider, force });
+      return;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   if (command === "create") {
     if (args.length === 0) {
       console.error(
@@ -532,7 +573,7 @@ Providers: claude, codex, gemini, cursor`);
 
   if (command === "approve") {
     if (args.length === 0) {
-      console.error(`Usage for approve: nvst approve <requirement|project-context|test-plan|refactor-plan>`);
+      console.error(`Usage for approve: nvst approve <requirement|project-context|test-plan|prototype|refactor-plan>`);
       printUsage();
       process.exitCode = 1;
       return;
@@ -562,6 +603,11 @@ Providers: claude, codex, gemini, cursor`);
       return;
     }
 
+    if (subcommand === "prototype") {
+      await runApprovePrototype({ force });
+      return;
+    }
+
     if (subcommand === "refactor-plan") {
       await runApproveRefactorPlan({ force });
       return;
@@ -613,12 +659,11 @@ Providers: claude, codex, gemini, cursor`);
         } = parseOptionalIntegerFlag(postAgentArgs, "--iterations", 1);
         const {
           value: retryOnFail,
-          remainingArgs: postRetryArgs,
+          remainingArgs: unknownArgs,
         } = parseOptionalIntegerFlag(postIterationsArgs, "--retry-on-fail", 0);
 
-        const { remainingArgs: postForceArgs } = parseForce(postRetryArgs);
-        if (postForceArgs.length > 0) {
-          console.error(`Unknown option(s) for execute automated-fix: ${postForceArgs.join(" ")}`);
+        if (unknownArgs.length > 0) {
+          console.error(`Unknown option(s) for execute automated-fix: ${unknownArgs.join(" ")}`);
           printUsage();
           process.exitCode = 1;
           return;