@quinteroac/agents-coding-toolkit 0.1.0-preview

package/scaffold/.agents/tmpl_state.example.json

@@ -0,0 +1,26 @@
+{
+  "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-02-18T12:00:00Z",
+  "history": []
+}

package/scaffold/.agents/tmpl_state_rules.md

@@ -0,0 +1,29 @@
+# State validation rules (scaffold)
+
+<!-- TODO: Fill in preconditions and postconditions per command. All content in English. -->
+
+Each command must validate the relevant fields of `state.json` before running. If the current state does not allow the command, the command fails with a clear message.
+
+| Command | Pre | Post |
+|--------|-----|-----|
+| `bun start iteration` | TBD | TBD |
+| `bun define requirement` | TBD | TBD |
+| `bun refine requirement` | TBD | TBD |
+| `bun approve requirement` | TBD | TBD |
+| `bun create prd` | TBD | TBD |
+| `bun create project-context` | TBD | TBD |
+| `bun approve project-context` | TBD | TBD |
+| `bun create prototype` | TBD | TBD |
+| `bun define test-plan` | TBD | TBD |
+| `bun refine test-plan` | TBD | TBD |
+| `bun approve test-plan` | TBD | TBD |
+| `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 |
+| `bun create prd --refactor` | TBD | TBD |
+| `bun execute refactor` | TBD | TBD |
+| `bun register changelog` (or equivalent) | TBD | TBD |

package/scaffold/docs/nvst-flow/templates/tmpl_CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+<!-- TODO: All content in English. One block per iteration. -->
+
+## [Unreleased]
+
+<!-- TODO -->
+
+## Iteration 000001 — YYYY-MM-DD
+
+<!-- TODO: Summary of requirements, refactorings, fixes. -->
+
+---
+
+<!-- Template for next iteration:
+## Iteration 000002 — YYYY-MM-DD
+...
+-->

package/scaffold/docs/nvst-flow/templates/tmpl_TECHNICAL_DEBT.md

@@ -0,0 +1,11 @@
+# Technical debt (discarded or deferred)
+
+<!-- TODO: All content in English. Updated when approving refactor plan (bun approve refactor-plan). Used as input in future iteration evaluations. -->
+
+## From iteration 000001
+
+<!-- TODO: Items not included in the refactor plan; rationale optional. -->
+
+---
+
+<!-- Add new section per iteration when refactor plan is approved. -->

package/scaffold/docs/nvst-flow/templates/tmpl_it_000001_evaluation-report.md

@@ -0,0 +1,19 @@
+# Evaluation report — Iteration 000001
+
+<!-- TODO: Replace 000001 with current iteration. Complete sections. All content in English. -->
+
+## Strengths
+
+<!-- TODO -->
+
+## Technical debt
+
+<!-- TODO: Items to consider for refactor. -->
+
+## Violations of PROJECT_CONTEXT.md
+
+<!-- TODO -->
+
+## Recommendations
+
+<!-- TODO: By impact, urgency, effort, scope; optional numeric score for ordering. -->

package/scaffold/docs/nvst-flow/templates/tmpl_it_000001_product-requirement-document.md

@@ -0,0 +1,19 @@
+# Product requirement document — Iteration 000001
+
+<!-- TODO: Replace 000001 with current iteration. Complete sections. All content in English. -->
+
+## Summary
+
+<!-- TODO -->
+
+## Requirements
+
+<!-- TODO: List requirements / user stories. -->
+
+## Acceptance criteria
+
+<!-- TODO -->
+
+## Out of scope (this iteration)
+
+<!-- TODO -->

package/scaffold/docs/nvst-flow/templates/tmpl_it_000001_refactor_plan.md

@@ -0,0 +1,19 @@
+# Refactor plan — Iteration 000001
+
+<!-- TODO: Replace 000001 with current iteration. Complete sections. All content in English. -->
+
+## Quick wins
+
+<!-- TODO -->
+
+## Critical refactorings
+
+<!-- TODO -->
+
+## Deferred / discarded (→ TECHNICAL_DEBT.md)
+
+<!-- TODO -->
+
+## Order of execution
+
+<!-- TODO: Ordered list of refactor steps. -->

package/scaffold/docs/nvst-flow/templates/tmpl_it_000001_test-plan.md

@@ -0,0 +1,19 @@
+# Test plan — Iteration 000001
+
+<!-- TODO: Replace 000001 with current iteration. Complete sections. All content in English. -->
+
+## Scope
+
+<!-- TODO: What is in scope for testing this iteration. -->
+
+## Automated tests
+
+<!-- TODO: List test cases; link to use cases / progress.json entries. -->
+
+## Exploratory / manual tests
+
+<!-- TODO: UX, exploratory; owned by user. -->
+
+## Environment and data
+
+<!-- TODO if needed -->

package/scaffold/schemas/node-shims.d.ts

@@ -0,0 +1,15 @@
+declare module "fs" {
+  export function readFileSync(path: string, encoding: string): string;
+}
+
+declare module "path" {
+  export function join(...paths: string[]): string;
+}
+
+declare const process: {
+  exitCode?: number;
+};
+
+interface ImportMeta {
+  readonly dir: string;
+}

package/scaffold/schemas/tmpl_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/scaffold/schemas/tmpl_prd.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+const acceptanceCriterion = z.object({
+    id: z.string(),
+    text: z.string(),
+});
+
+const userStory = z.object({
+    id: z.string(),
+    title: z.string(),
+    description: z.string(),
+    acceptanceCriteria: z.array(acceptanceCriterion),
+});
+
+const functionalRequirement = z.object({
+    id: z.string(),
+    description: z.string(),
+});
+
+export const PrdSchema = z.object({
+    goals: z.array(z.string()),
+    userStories: z.array(userStory),
+    functionalRequirements: z.array(functionalRequirement),
+});
+
+export type Prd = z.infer<typeof PrdSchema>;

package/scaffold/schemas/tmpl_progress.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+const implementationStatus = z.enum(["pending", "in_progress", "completed"]);
+const testStatus = z.enum([
+  "pending",
+  "written",
+  "passed",
+  "failed",
+  "fixed",
+  "unfixed",
+]);
+
+const implementation = z.object({
+  status: implementationStatus,
+  summary_of_actions: z.string(),
+  learnings: z.string(),
+});
+
+const testEntry = z.object({
+  id: z.string(),
+  description: z.string(),
+  status: testStatus,
+  file: z.string().optional(),
+  last_run: z.string().optional(),
+  error: z.string().optional(),
+});
+
+const progressEntry = z.object({
+  use_case_id: z.string(),
+  timestamp: z.string(),
+  implementation,
+  tests: z.array(testEntry),
+});
+
+export const ProgressSchema = z.object({
+  entries: z.array(progressEntry),
+});
+
+export type Progress = z.infer<typeof ProgressSchema>;

package/scaffold/schemas/tmpl_state.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+
+const iterationId = z.string().regex(/^\d{6}$/);
+const phase = z.enum(["define", "prototype", "refactor"]);
+const iso8601 = z.string(); // TODO: tighten to ISO 8601 regex if desired
+
+const statusFile = z.object({
+  status: z.string(),
+  file: z.string().nullable(),
+});
+
+const definePhase = z.object({
+  requirement_definition: z.object({
+    status: z.enum(["pending", "in_progress", "approved"]),
+    file: z.string().nullable(),
+  }),
+  prd_generation: z.object({
+    status: z.enum(["pending", "completed"]),
+    file: z.string().nullable(),
+  }),
+});
+
+const prototypePhase = z.object({
+  project_context: statusFile.extend({
+    status: z.enum(["pending", "pending_approval", "created"]),
+  }),
+  test_plan: statusFile.extend({
+    status: z.enum(["pending", "pending_approval", "created"]),
+  }),
+  tp_generation: z.object({
+    status: z.enum(["pending", "created"]),
+    file: z.string().nullable(),
+  }),
+  prototype_build: statusFile.extend({
+    status: z.enum(["pending", "in_progress", "created"]),
+  }),
+  test_execution: statusFile.extend({
+    status: z.enum(["pending", "in_progress", "completed", "failed"]),
+  }),
+  prototype_approved: z.boolean(),
+});
+
+const refactorPhase = z.object({
+  evaluation_report: z.object({
+    status: z.enum(["pending", "created"]),
+    file: z.string().nullable(),
+  }),
+  refactor_plan: z.object({
+    status: z.enum(["pending", "pending_approval", "approved"]),
+    file: z.string().nullable(),
+  }),
+  refactor_execution: z.object({
+    status: z.enum(["pending", "in_progress", "completed"]),
+    file: z.string().nullable(),
+  }),
+  changelog: z.object({
+    status: z.enum(["pending", "created"]),
+    file: z.string().nullable(),
+  }),
+});
+
+const historyEntry = z.object({
+  iteration: iterationId,
+  archived_at: iso8601,
+  archived_path: z.string(),
+});
+
+export const StateSchema = z.object({
+  current_iteration: iterationId,
+  current_phase: phase,
+  phases: z.object({
+    define: definePhase,
+    prototype: prototypePhase,
+    refactor: refactorPhase,
+  }),
+  last_updated: iso8601,
+  updated_by: z.string().optional(),
+  history: z.array(historyEntry).optional(),
+});
+
+export type State = z.infer<typeof StateSchema>;

package/scaffold/schemas/tmpl_test-plan.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+const TestStatusSchema = z.enum(["pending", "passed", "failed", "skipped"]);
+
+const TestItemSchema = z.object({
+  id: z.string(),
+  description: z.string(),
+  status: TestStatusSchema,
+  correlatedRequirements: z.array(z.string()),
+});
+
+export const TestPlanSchema = z.object({
+  overallStatus: TestStatusSchema,
+  scope: z.array(z.string()),
+  environmentData: z.array(z.string()),
+  automatedTests: z.array(TestItemSchema),
+  exploratoryManualTests: z.array(TestItemSchema),
+});
+
+export type TestPlan = z.infer<typeof TestPlanSchema>;

package/scaffold/schemas/tmpl_validate-progress.ts

@@ -0,0 +1,13 @@
+import { ProgressSchema } from "./tmpl_progress";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const path = join(import.meta.dir, "..", ".agents", "flow", "tmpl_it_000001_progress.example.json");
+const raw = JSON.parse(await readFile(path, "utf-8"));
+const result = ProgressSchema.safeParse(raw);
+if (result.success) {
+  console.log("tmpl_it_000001_progress.example.json is valid");
+} else {
+  console.error("Validation failed:", result.error.flatten());
+  process.exitCode = 1;
+}

package/scaffold/schemas/tmpl_validate-state.ts

@@ -0,0 +1,13 @@
+import { StateSchema } from "./tmpl_state";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const path = join(import.meta.dir, "..", ".agents", "tmpl_state.example.json");
+const raw = JSON.parse(await readFile(path, "utf-8"));
+const result = StateSchema.safeParse(raw);
+if (result.success) {
+  console.log("tmpl_state.example.json is valid");
+} else {
+  console.error("tmpl_state.example.json validation failed:", result.error.flatten());
+  process.exitCode = 1;
+}

package/scaffold/tmpl_AGENTS.md

@@ -0,0 +1,7 @@
+# Agents entry point
+
+- **What this project is:** (Describe the product or project. This file is the single entry point for the agent.)
+- **How to work here:** Use this file as the single entry point. Follow the process phases in order; read and update `.agents/state.json` for the current iteration and phase. Invoke the skills under `.agents/skills/` as indicated by each command. All iteration artifacts live in `.agents/flow/` with the naming `it_` + 6-digit iteration (e.g. `it_000001_product-requirement-document.md`). From the second iteration onward, adhere to `.agents/PROJECT_CONTEXT.md`.
+- **Process:** Define → Prototype → Refactor (see package or usage documentation).
+- **Project context:** `.agents/PROJECT_CONTEXT.md` (conventions and architecture; agent adheres from second iteration onward).
+- **Rule:** All generated resources in this repo must be in English.

package/schemas/prd.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+const acceptanceCriterion = z.object({
+    id: z.string(),
+    text: z.string(),
+});
+
+const userStory = z.object({
+    id: z.string(),
+    title: z.string(),
+    description: z.string(),
+    acceptanceCriteria: z.array(acceptanceCriterion),
+});
+
+const functionalRequirement = z.object({
+    id: z.string(),
+    description: z.string(),
+});
+
+export const PrdSchema = z.object({
+    goals: z.array(z.string()),
+    userStories: z.array(userStory),
+    functionalRequirements: z.array(functionalRequirement),
+});
+
+export type Prd = z.infer<typeof PrdSchema>;

package/schemas/progress.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+const implementationStatus = z.enum(["pending", "in_progress", "completed"]);
+const testStatus = z.enum([
+  "pending",
+  "written",
+  "passed",
+  "failed",
+  "fixed",
+  "unfixed",
+]);
+
+const implementation = z.object({
+  status: implementationStatus,
+  summary_of_actions: z.string(),
+  learnings: z.string(),
+});
+
+const testEntry = z.object({
+  id: z.string(),
+  description: z.string(),
+  status: testStatus,
+  file: z.string().optional(),
+  last_run: z.string().optional(),
+  error: z.string().optional(),
+});
+
+const progressEntry = z.object({
+  use_case_id: z.string(),
+  timestamp: z.string(),
+  implementation,
+  tests: z.array(testEntry),
+});
+
+export const ProgressSchema = z.object({
+  entries: z.array(progressEntry),
+});
+
+export type Progress = z.infer<typeof ProgressSchema>;

package/schemas/state.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+
+const iterationId = z.string().regex(/^\d{6}$/);
+const phase = z.enum(["define", "prototype", "refactor"]);
+const iso8601 = z.string(); // TODO: tighten to ISO 8601 regex if desired
+
+const statusFile = z.object({
+  status: z.string(),
+  file: z.string().nullable(),
+});
+
+const definePhase = z.object({
+  requirement_definition: z.object({
+    status: z.enum(["pending", "in_progress", "approved"]),
+    file: z.string().nullable(),
+  }),
+  prd_generation: z.object({
+    status: z.enum(["pending", "completed"]),
+    file: z.string().nullable(),
+  }),
+});
+
+const prototypePhase = z.object({
+  project_context: statusFile.extend({
+    status: z.enum(["pending", "pending_approval", "created"]),
+  }),
+  test_plan: statusFile.extend({
+    status: z.enum(["pending", "pending_approval", "created"]),
+  }),
+  tp_generation: z.object({
+    status: z.enum(["pending", "created"]),
+    file: z.string().nullable(),
+  }),
+  prototype_build: statusFile.extend({
+    status: z.enum(["pending", "in_progress", "created"]),
+  }),
+  test_execution: statusFile.extend({
+    status: z.enum(["pending", "in_progress", "completed", "failed"]),
+  }),
+  prototype_approved: z.boolean(),
+});
+
+const refactorPhase = z.object({
+  evaluation_report: z.object({
+    status: z.enum(["pending", "created"]),
+    file: z.string().nullable(),
+  }),
+  refactor_plan: z.object({
+    status: z.enum(["pending", "pending_approval", "approved"]),
+    file: z.string().nullable(),
+  }),
+  refactor_execution: z.object({
+    status: z.enum(["pending", "in_progress", "completed"]),
+    file: z.string().nullable(),
+  }),
+  changelog: z.object({
+    status: z.enum(["pending", "created"]),
+    file: z.string().nullable(),
+  }),
+});
+
+const historyEntry = z.object({
+  iteration: iterationId,
+  archived_at: iso8601,
+  archived_path: z.string(),
+});
+
+export const StateSchema = z.object({
+  current_iteration: iterationId,
+  current_phase: phase,
+  phases: z.object({
+    define: definePhase,
+    prototype: prototypePhase,
+    refactor: refactorPhase,
+  }),
+  last_updated: iso8601,
+  updated_by: z.string().optional(),
+  history: z.array(historyEntry).optional(),
+});
+
+export type State = z.infer<typeof StateSchema>;

package/schemas/test-plan.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+
+import { TestPlanSchema } from "./test-plan";
+
+describe("TestPlanSchema", () => {
+  test("accepts enhanced test plan metadata structure", () => {
+    const validation = TestPlanSchema.safeParse({
+      overallStatus: "pending",
+      scope: ["Validate login flow and session persistence"],
+      environmentData: ["Node 22", "Chromium latest", "seeded test users"],
+      automatedTests: [
+        {
+          id: "TC-001",
+          description: "POST /login returns 200 for valid credentials",
+          status: "passed",
+          correlatedRequirements: ["US-001", "FR-1"],
+        },
+      ],
+      exploratoryManualTests: [
+        {
+          id: "TC-002",
+          description: "Visual check of error message clarity for invalid login",
+          status: "skipped",
+          correlatedRequirements: ["US-001"],
+        },
+      ],
+    });
+
+    expect(validation.success).toBe(true);
+    if (!validation.success) {
+      throw new Error("Expected enhanced test plan payload to be valid");
+    }
+
+    expect(validation.data.overallStatus).toBe("pending");
+    expect(validation.data.environmentData).toEqual([
+      "Node 22",
+      "Chromium latest",
+      "seeded test users",
+    ]);
+    expect(validation.data.automatedTests[0]?.correlatedRequirements).toEqual(["US-001", "FR-1"]);
+  });
+
+  test("rejects legacy flat-list schema shape", () => {
+    const validation = TestPlanSchema.safeParse({
+      scope: ["Legacy scope"],
+      automatedTests: ["legacy test line item"],
+      exploratoryManualTests: ["legacy manual line item"],
+      environmentAndData: ["legacy env entry"],
+    });
+
+    expect(validation.success).toBe(false);
+  });
+});

package/schemas/test-plan.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+const TestStatusSchema = z.enum(["pending", "passed", "failed", "skipped"]);
+
+const TestItemSchema = z.object({
+  id: z.string(),
+  description: z.string(),
+  status: TestStatusSchema,
+  correlatedRequirements: z.array(z.string()),
+});
+
+export const TestPlanSchema = z.object({
+  overallStatus: TestStatusSchema,
+  scope: z.array(z.string()),
+  environmentData: z.array(z.string()),
+  automatedTests: z.array(TestItemSchema),
+  exploratoryManualTests: z.array(TestItemSchema),
+});
+
+export type TestPlan = z.infer<typeof TestPlanSchema>;

package/schemas/validate-progress.ts

@@ -0,0 +1,13 @@
+import { ProgressSchema } from "./tmpl_progress.ts";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const path = join(import.meta.dir, "..", ".agents", "flow", "tmpl_it_000001_progress.example.json");
+const raw = JSON.parse(await readFile(path, "utf-8"));
+const result = ProgressSchema.safeParse(raw);
+if (result.success) {
+  console.log("tmpl_it_000001_progress.example.json is valid");
+} else {
+  console.error("Validation failed:", result.error.flatten());
+  process.exitCode = 1;
+}

package/schemas/validate-state.ts

@@ -0,0 +1,13 @@
+import { StateSchema } from "./tmpl_state.ts";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const path = join(import.meta.dir, "..", ".agents", "tmpl_state.example.json");
+const raw = JSON.parse(await readFile(path, "utf-8"));
+const result = StateSchema.safeParse(raw);
+if (result.success) {
+  console.log("tmpl_state.example.json is valid");
+} else {
+  console.error("tmpl_state.example.json validation failed:", result.error.flatten());
+  process.exitCode = 1;
+}