@quinteroac/agents-coding-toolkit 0.1.0-preview

package/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/README.md

@@ -0,0 +1,127 @@
+# Nerds Vibecoding Survivor Toolkit
+
+> 🚧 **Work in Progress**: This toolkit is currently under active development.
+
+## Purpose
+
+This repository contains nerds-vst (Nerd's Vibecoding Survivor Toolkit).
+
+nerds-vst is a framework and command-line tool built on Bun, designed to help you create and develop projects from scratch using a specification-driven development pattern powered by AI coding—a process informally known as vibecoding. This repository is the toolkit implementation; usage and workflow documentation will be published with the package.
+
+The framework is built on the following principles:
+
+- Single source of truth — State is centralized, minimizing the risk of AI hallucination and reducing ambiguity.
+- Context is everything — Leveraging diverse project context and specialized skills helps both AI and humans to better understand and reason about the project.
+- Human in the loop — Mandatory review and decision points ensure that humans define and validate key steps in every iteration.
+- Build fast / Fail fast — Developers can grant AI a controlled degree of autonomy to enable rapid prototyping, embodying the agile principle of building quickly and embracing early failure.
+- Iterative development — Strongly encourages building software incrementally, block by block, allowing time to refactor and address technical debt during each iteration instead of all at once.
+- Agnostic agent support — Whether you prefer Claude, Codex, Gemini, or another CLI-based agent, the toolkit is designed to easily integrate with most agent providers and lets you choose or combine the tools that best fit your workflow.
+
+
+## Features
+
+nerds-vst is a package that provides:
+
+- **Scaffold tool** — Running `bun nvst init` copies the template from this repo’s `scaffold/` directory into the target project, creating the following structure:
+
+  ```
+  AGENTS.md
+  iteration_close_checklist.md
+  ralph_loop.md
+  providers.md
+  .agents/
+    PROJECT_CONTEXT.md
+    state.json
+    state_rules.md
+    scripts/
+      ralph.ts
+    skills/
+      create-pr-document/SKILL.md
+      refine-pr-document/SKILL.md
+      create-project-context/SKILL.md
+      refine-project-context/SKILL.md
+      create-test-plan/SKILL.md
+      refine-test-plan/SKILL.md
+      implement-user-story/SKILL.md
+      create-issue/SKILL.md
+      execute-test-case/SKILL.md
+      execute-test-batch/SKILL.md
+      evaluate/SKILL.md
+      plan-refactor/SKILL.md
+      refactor-prd/SKILL.md
+      debug/SKILL.md
+    flow/
+      README.md
+      archived/
+  docs/templates/
+    CHANGELOG.md
+    TECHNICAL_DEBT.md
+  schemas/
+    state.ts
+    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.
+
+- **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.
+
+  **Command summary** (see [process_design.md](process_design.md) for full details):
+
+  | Phase | Commands |
+  |-------|----------|
+  | **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` |
+  | **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 |
+
+
+## Installation
+
+**Prerequisites:** [Bun](https://bun.sh/) v1 or later must be installed.
+
+You can install the toolkit from the local file system or from a registry (when published).
+
+### From local file system
+
+Install from a local directory or a packed tarball:
+
+```bash
+# From project root
+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
+```
+
+### From npm
+
+When the package is published to npm:
+
+```bash
+bun add @quinteroac/agents-coding-toolkit
+# or
+npm install @quinteroac/agents-coding-toolkit
+```
+
+### Verify installation
+
+After installation, the `nvst` command should be available:
+
+```bash
+# Check that the command works
+nvst --help
+
+# Verify installed version matches the package
+nvst --version
+```
+
+## Acknowledgement
+
+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).

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@quinteroac/agents-coding-toolkit",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "version": "0.1.0-preview",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quinteroac/nerds-vibecoding-survivor-toolkit.git"
+  },
+  "bin": { "nvst": "src/cli.ts" },
+  "files": [
+    "src",
+    "scaffold",
+    "schemas",
+    "AGENTS.md",
+    "README.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "package": "npm pack",
+    "validate:state": "bun run scaffold/schemas/tmpl_validate-state.ts",
+    "validate:progress": "bun run scaffold/schemas/tmpl_validate-progress.ts"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9",
+    "@types/node": "^25.3.0",
+    "typescript": "^5.6.3"
+  }
+}

package/scaffold/.agents/flow/tmpl_README.md

@@ -0,0 +1,7 @@
+# Flow directory (scaffold)
+
+<!-- TODO: Complete. All content in English. -->
+
+- **What lives here:** TBD — Iteration artifacts `it_<6 digits>_*` (e.g. product-requirement-document.md, PRD.json, progress.json, test-plan.md, evaluation-report.md, refactor_plan.md).
+- **Naming:** Prefix `it_` + 6-digit iteration number (e.g. `it_000001_`, `it_000042_`). No spaces.
+- **What gets archived:** When starting the next iteration, current iteration files move to `.agents/flow/archived/<iteration>/` (e.g. `archived/000001/`).

package/scaffold/.agents/flow/tmpl_iteration_close_checklist.example.md

@@ -0,0 +1,11 @@
+# Iteration close checklist (scaffold)
+
+<!-- TODO: Complete. All content in English. Use when closing an iteration (before running start next iteration / archive). -->
+
+- [ ] **prototype_approved** — Prototype has been approved (`phases.prototype.prototype_approved === true`).
+- [ ] **Full tests** — Tests for all use cases of the iteration (original + refactor/regression) have been run and pass (or documented exceptions).
+- [ ] **PROJECT_CONTEXT.md** — Updated with newly implemented features; summary mechanism applied so file does not exceed 250 lines.
+- [ ] **CHANGELOG.md** — Iteration summary recorded (requirements, refactorings, fixes).
+- [ ] **Archive** — Ready to run “start iteration” (move `it_<iteration>_*` to `.agents/flow/archived/<iteration>/`, update state.history, reset phase for next iteration).
+
+TBD — Add any project-specific items.

package/scaffold/.agents/skills/automated-fix/tmpl_SKILL.md

@@ -0,0 +1,67 @@
+---
+name: automated-fix
+description: "Fixes one issue from the iteration issues list by reproducing, diagnosing, and resolving it. Invoked by: bun nvst fix issue."
+user-invocable: false
+---
+
+# Automated Fix
+
+Attempt to resolve the provided issue safely and deterministically by following a structured debugging workflow.
+
+---
+
+## Inputs
+
+| Source | Used for |
+|--------|----------|
+| `issue` (context variable) | The issue to fix, including id, title, description, and reproduction steps |
+| `project_context` (context variable) | Project conventions, tech stack, code standards, testing strategy, and architecture |
+| `iteration` (context variable) | Current iteration number for file naming and context |
+
+---
+
+## The Job
+
+Follow this debugging workflow in order:
+
+1. Understand the issue — read the description and any reproduction steps carefully.
+2. Reproduce the issue — confirm it is observable before making any changes.
+3. Form hypotheses — identify possible root causes based on the observed behaviour.
+4. Identify affected code — locate the files and functions involved.
+5. Add instrumentation if needed — add temporary logging or assertions to narrow down the cause.
+6. Collect logs — run the code and capture output if instrumentation was added.
+7. Confirm or discard hypotheses — use evidence to settle on the root cause.
+8. Fix the issue — apply the minimal change that resolves the root cause.
+9. Verify the fix — attempt to reproduce the original issue and confirm it no longer occurs.
+10. Remove instrumentation — clean up any temporary logging or assertions added in step 5.
+
+---
+
+## Rules
+
+- **Minimal scope.** Keep changes scoped to the provided issue — do not refactor unrelated code.
+- **Add or update tests.** Write or update tests to cover the fix when appropriate.
+- **Do not commit.** The calling command handles git commits.
+- **Stop on uncertainty.** If no hypothesis can be confirmed after reasonable effort, stop and report failure rather than guessing.
+- **Follow conventions exactly.** Use the naming, formatting, error handling, and module organisation patterns from the project context.
+
+---
+
+## Output
+
+The output is the set of file changes (modified or new files) in the working tree. There is no document to produce — the corrected code and any updated tests are the deliverable.
+
+---
+
+## Checklist
+
+Before finishing:
+
+- [ ] Issue was reproduced before any changes were made
+- [ ] Root cause was identified and confirmed
+- [ ] Fix is minimal and scoped to the provided issue
+- [ ] Issue can no longer be reproduced after the fix
+- [ ] Instrumentation has been removed
+- [ ] Tests were added or updated where appropriate
+- [ ] Code follows project conventions (naming, style, error handling)
+- [ ] No git commits were made

package/scaffold/.agents/skills/create-issue/tmpl_SKILL.md

@@ -0,0 +1,68 @@
+---
+name: create-issue
+description: "Interactively defines one or more issues with the user. Triggered by: bun nvst create issue --agent <provider>."
+user-invocable: true
+---
+
+# Create Issue
+
+Define one or more issues interactively with the user and write them to the output file using `write-json`.
+
+**Important:** Do NOT fix the issues. Just gather information and produce the output file.
+
+---
+
+## The Job
+
+1. Ask the user what issue(s) they want to create. Gather a `title` and `description` for each issue.
+2. Ask clarifying questions one at a time until you have enough detail.
+3. Run the `write-json` command to write the issues file (see Output section).
+
+---
+
+## Questions Flow
+
+**CRITICAL: Ask ONE question at a time. Wait for the user's answer before asking the next question.**
+
+1. Describe the issue — what is the problem or task?
+2. Is there additional context (error messages, affected files, reproduction steps)?
+3. Are there more issues to add? If yes, repeat questions 1–2.
+
+---
+
+## Output
+
+When you have collected all issues, write the file by running:
+
+```bash
+bun run src/cli.ts write-json --schema issues --out .agents/flow/it_{iteration}_ISSUES.json --data '<json>'
+```
+
+Replace `{iteration}` with the value from Context (e.g. `000009`). The JSON must be a valid array where each element has:
+
+- `id`: `ISSUE-{iteration}-001`, `ISSUE-{iteration}-002`, etc. (sequential, zero-padded)
+- `title`: concise summary (one sentence)
+- `description`: detailed explanation including context, reproduction steps, or expected behaviour
+- `status`: always `"open"`
+
+Example:
+
+```json
+[
+  {"id": "ISSUE-000009-001", "title": "Short issue title", "description": "Detailed description.", "status": "open"},
+  {"id": "ISSUE-000009-002", "title": "Another issue", "description": "More details.", "status": "open"}
+]
+```
+
+**You must run the write-json command.** Do not output JSON to stdout alone. The calling system expects the file to exist.
+
+---
+
+## Checklist
+
+Before running write-json:
+
+- [ ] Each issue has a clear, specific `title`
+- [ ] Each issue has a detailed `description`
+- [ ] Each issue has correct `id` (ISSUE-{iteration}-NNN) and `status` ("open")
+- [ ] Write the file via `bun run src/cli.ts write-json ...`

package/scaffold/.agents/skills/create-pr-document/tmpl_SKILL.md

@@ -0,0 +1,125 @@
+---
+name: create-pr-document
+description: "Gathers the requirement from the user and produces it_{iteration}_product-requirement-document.md. Triggered by: bun nvst define requirement."
+user-invocable: true
+---
+
+# Create Product Requirement Document
+
+Produce `it_{current_iteration}_product-requirement-document.md` in `.agents/flow/` by interviewing the user about the feature or change they want to build.
+
+**Important:** Do NOT start implementing. Just gather the requirement and write the document.
+
+---
+
+## The Job
+
+1. **Understand the project first.** Read `AGENTS.md`, `.agents/PROJECT_CONTEXT.md`, and explore the codebase structure (main entry points, conventions, existing features) before starting the interview. This context will make your questions more relevant and the PRD better aligned with the project.
+2. Read `state.json` to get `current_iteration` (6-digit string, e.g. `"000001"`).
+3. Ask 3–5 clarifying questions (see Questions Flow).
+4. Generate the document following the Output Structure.
+5. Write to `.agents/flow/it_{current_iteration}_product-requirement-document.md`.
+6. Update `state.json`: `requirement_definition.status` = `"in_progress"`, `requirement_definition.file` = filename.
+
+---
+
+## Questions Flow
+
+**CRITICAL: Ask ONE question at a time. Wait for the user's answer before asking the next question. Do NOT present all questions at once.**
+
+Ask only questions where the initial prompt is ambiguous. Present lettered options so the user can reply with short codes (e.g. "1A").
+
+Questions to ask (one by one, in order):
+
+1. What problem does this solve or goal does it achieve?
+   - A. [inferred option]
+   - B. [inferred option]
+   - C. Other: [please specify]
+
+*(Wait for answer, then ask question 2)*
+
+2. Who is the primary user or actor?
+   - A. End user / customer
+   - B. Internal operator / admin
+   - C. Another system or automated process
+   - D. Other: [specify]
+
+*(Wait for answer, then ask question 3)*
+
+3. MVP scope — what is the minimum set of use cases needed to validate the idea?
+   List only the user stories you consider strictly necessary.
+   *(e.g. "UC-1: user can log in, UC-2: user can view dashboard")*
+
+*(Wait for answer, then ask question 4)*
+
+4. Are there hard constraints (deadline, platform, dependencies)?
+   *(Skip if the user says none)*
+
+*(Wait for answer, then ask question 5)*
+
+5. What does "done" look like? How will we know it works?
+   *(Describe acceptance criteria or how you'd verify success)*
+
+*(Wait for answer, then generate the document)*
+
+---
+
+## Output Structure
+
+```markdown
+# Requirement: [Feature or Change Name]
+
+## Context
+Brief description of the problem or opportunity this addresses.
+
+## Goals
+- [Specific, measurable objective]
+- …
+
+## User Stories
+Each story must be small enough to implement in one focused session.
+
+### US-001: [Title]
+**As a** [actor], **I want** [capability] **so that** [benefit].
+
+**Acceptance Criteria:**
+- [ ] [Specific, verifiable criterion — not vague]
+- [ ] [Another criterion]
+- [ ] Typecheck / lint passes
+- [ ] **[UI stories only]** Visually verified in browser
+
+### US-002: …
+
+## Functional Requirements
+- FR-1: …
+- FR-2: …
+
+## Non-Goals (Out of Scope)
+- …
+
+## Open Questions
+- …
+```
+
+---
+
+## Writing Guidelines
+
+- **MVP first:** include only the user stories from the answer to question 3. If the user did not list explicit stories, propose the smallest set possible and confirm before writing. Do not pad scope.
+- Be explicit and unambiguous — the reader may be a junior developer or an AI agent.
+- Acceptance criteria must be verifiable: "button shows confirmation dialog before deleting" ✓ — "works correctly" ✗.
+- Every story with a UI change must include browser verification as an acceptance criterion.
+- Number requirements (`FR-N`) for easy cross-reference with `it_{iteration}_PRD.json`.
+
+---
+
+## Checklist
+
+Before saving:
+
+- [ ] Clarifying questions asked and answered
+- [ ] Each user story has verifiable acceptance criteria
+- [ ] Functional requirements are numbered and unambiguous
+- [ ] Non-goals define clear scope boundaries
+- [ ] File written to `.agents/flow/it_{current_iteration}_product-requirement-document.md`
+- [ ] `state.json` → `requirement_definition.status` = `"in_progress"`, `requirement_definition.file` set

package/scaffold/.agents/skills/create-project-context/tmpl_SKILL.md

@@ -0,0 +1,168 @@
+---
+name: create-project-context
+description: "Creates or updates .agents/PROJECT_CONTEXT.md with project conventions, tech stack, code standards, testing strategy, and product architecture. Triggered by: bun nvst create project-context."
+user-invocable: true
+---
+
+# Create / Update Project Context
+
+Create or update `.agents/PROJECT_CONTEXT.md` so the agent has a single, stable reference for conventions and architecture across all iterations.
+
+---
+
+## The Job
+
+1. Check whether `.agents/PROJECT_CONTEXT.md` already exists.
+   - **First iteration (file absent or empty):** run the Questions flow below.
+   - **Subsequent iterations (file present):** ask the user what to add or change; skip questions for sections already covered. In `--mode yolo` skip all questions and infer from the codebase and the current iteration's PRD.
+2. Produce or update the document following the Output Structure.
+3. Enforce the **250-line cap** (see Cap Rule).
+4. Write the result to `.agents/PROJECT_CONTEXT.md`.
+
+---
+
+## Inputs
+
+| Source | Used for |
+|--------|----------|
+| `it_{iteration}_product-requirement-document.md` | Understanding product goals and implied stack/conventions |
+| `it_{iteration}_PRD.json` | Use cases and scope of the current iteration |
+| `.agents/PROJECT_CONTEXT.md` (if present) | Existing content to preserve or update |
+| User answers (interactive mode) | Filling in sections that cannot be inferred |
+
+---
+
+## Questions Flow (first iteration or missing sections)
+
+Ask only about sections that cannot be confidently inferred from the PRD and codebase. Present lettered options where applicable so the user can reply with short codes (e.g. "1A, 2B").
+
+```
+1. Primary language(s) and runtime?
+   A. TypeScript / Node.js
+   B. Python
+   C. Go
+   D. Rust
+   E. TypeScript (frontend) + Python (backend)
+   F. TypeScript (frontend) + Go (backend)
+   G. TypeScript (frontend) + Rust (backend)
+   H. Other: [specify]
+
+2. Main framework(s)?
+   A. Next.js
+   B. React + Vite
+   C. FastAPI / Flask
+   D. Gin / Echo / Fiber (Go)
+   E. Actix-web / Axum (Rust)
+   F. Other: [specify]
+
+3. Package manager?
+   A. bun
+   B. npm
+   C. pnpm
+   D. yarn
+
+4. Test approach?
+   A. TDD — tests first, then code
+   B. Code first, tests after
+   C. Tests only for critical paths
+
+5. Test runner?
+   A. Vitest
+   B. Jest
+   C. Pytest
+   D. Go built-in (`go test`)
+   E. Rust built-in (`cargo test`)
+   F. Other: [specify]
+
+6. Git flow?
+   A. Feature branches per iteration (feature/it_XXXXXX)
+   B. Trunk-based (commits directly to main)
+   C. Other: [specify]
+
+7. Style / formatting conventions?
+   A. Prettier + ESLint defaults
+   B. Project-specific config (already committed)
+   C. `gofmt` / `goimports` (Go — enforced by default)
+   D. `rustfmt` (Rust — enforced by default)
+   E. No enforced formatting
+
+8. Any hard constraints (monorepo, deployment target, env restrictions)?
+   [Open answer — skip if none]
+```
+
+---
+
+## Output Structure
+
+Write `.agents/PROJECT_CONTEXT.md` using only the sections relevant to the project. Include all sections that have content; omit those that are genuinely not applicable.
+
+```markdown
+# Project Context
+
+<!-- Created or updated by `bun nvst create project-context`. Cap: 250 lines. -->
+
+## Conventions
+- Naming: [files, variables, components]
+- Formatting: [tool + config]
+- Git flow: [branching strategy, commit convention]
+- Workflow: [any process agreement]
+
+## Tech Stack
+- Language(s): …
+- Runtime: …
+- Frameworks: …
+- Key libraries: …
+- Package manager: …
+- Build / tooling: …
+
+## Code Standards
+- Style patterns: …
+- Error handling: …
+- Module organisation: …
+- Forbidden patterns (if any): …
+
+## Testing Strategy
+- Approach: [TDD | code-first | critical-paths only]
+- Runner: …
+- Coverage targets (if any): …
+- Test location convention: …
+
+## Product Architecture
+- High-level diagram or description: …
+- Main components / layers: …
+- Data flow summary: …
+
+## Modular Structure
+- [package or module]: [responsibility]
+- …
+
+## Implemented Capabilities
+<!-- Updated at the end of each iteration by bun nvst create project-context -->
+- (none yet — populated after first Refactor)
+```
+
+---
+
+## Cap Rule (250 lines)
+
+Before writing the file, count projected line count.
+
+- If ≤ 250 lines → write as-is.
+- If > 250 lines → apply the summary mechanism **before** appending new content:
+  1. Condense the **Implemented Capabilities** section: group earlier iterations into a "Summary of previous iterations" block; keep full detail only for the last 1–2 iterations.
+  2. Shorten any section that has grown beyond 10 lines by merging or removing redundant entries.
+  3. If still over 250, move low-priority detail (e.g. full feature lists from old iterations) to `.agents/PROJECT_CONTEXT_archive.md` and replace with a one-line reference.
+- Re-count after summarisation; write only when ≤ 250 lines.
+
+---
+
+## Checklist
+
+Before saving the file:
+
+- [ ] All sections answered or explicitly marked N/A
+- [ ] Conventions are specific (not "follow best practices")
+- [ ] Tech stack lists exact versions where relevant
+- [ ] Testing strategy matches what the PRD implies
+- [ ] File does not exceed 250 lines
+- [ ] `state.json` → `project_context.status` set to `"pending_approval"` and `project_context.file` set to `".agents/PROJECT_CONTEXT.md"` after writing