valent-pipeline 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valent-pipeline",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "v3 multi-agent AI pipeline for software development lifecycle",
   "type": "module",
   "bin": {

package/skills/v3-setup-backlog/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: v3-setup-backlog
+description: 'Convert epics and stories into pipeline-ready backlog and story input files. Use when the user says "setup backlog", "import stories", "v3 setup", "prepare stories", or provides an epics/stories document to load into the pipeline.'
+argument-hint: '<path-to-epics-file or epic-id>'
+---
+
+# v3 Backlog Setup
+
+Convert an epics and stories document (any format — markdown, YAML, PRD extract, or pasted text) into the two things the pipeline needs:
+
+1. **`pipeline-backlog.yaml`** — ordered priority queue of stories with dependencies
+2. **`stories/{story-id}/story.md`** — individual story input files with ACs in Given-When-Then format
+
+## Step 1: Find the Source
+
+Check what the user provided:
+- If they gave a file path, read it
+- If they pasted text, use it directly
+- If they gave an epic ID, ask where the epics/stories document is
+
+The source can be in any format — a PRD, a BMAD epics file, a Jira export, a markdown list, a spreadsheet paste, etc. Your job is to extract stories from whatever they give you.
+
+## Step 2: Read Pipeline Config
+
+Read `v3/pipeline-config.yaml` to get:
+- `project.story_directory` — where to create story folders (default: `./stories`)
+- `project.backlog_path` — where to write the backlog (default: `./pipeline-backlog.yaml`)
+- `project.type` — affects which testing profiles are relevant
+
+## Step 3: Extract Stories
+
+From the source document, identify each story and extract:
+
+| Field | Required | Source |
+|---|---|---|
+| Story ID | Yes | Use existing IDs if present, or generate `{EPIC-PREFIX}-{NNN}` pattern |
+| Epic | Yes | The epic this story belongs to |
+| Title | Yes | One-line summary |
+| User story | Yes | "As a [role] I want [capability] so that [benefit]" |
+| Acceptance criteria | Yes | Testable conditions — convert to Given-When-Then if not already |
+| Priority | Yes | Integer, lower = higher. Derive from epic order + story order within epic |
+| Dependencies | No | Which stories must ship before this one can start (`depends_on`) |
+| Optional inputs | No | UX spec, architecture notes, scenario outlines if mentioned |
+
+**Priority assignment:** First story in first epic = 1, second story = 2, etc. Stories within the same epic are ordered by their natural sequence. Cross-epic dependencies use `depends_on`.
+
+**Dependency detection:** Look for:
+- Explicit "depends on" or "requires" references
+- Implicit: "API endpoint" stories should ship before "UI that calls the API" stories
+- Schema/migration stories should ship before stories that use those tables
+- Ask the user to confirm any inferred dependencies
+
+## Step 4: Present Summary for Approval
+
+Before writing any files, show the user:
+
+```
+Epic: {EPIC-NAME}
+  {STORY-ID}: {title} [priority: {N}] {depends_on if any}
+  {STORY-ID}: {title} [priority: {N}]
+  ...
+
+Epic: {EPIC-NAME}
+  ...
+
+Total: {N} stories across {M} epics
+Dependencies: {list any depends_on relationships}
+```
+
+Ask: "Does this look right? Any stories to add, remove, reorder, or re-prioritize?"
+
+## Step 5: Write Backlog
+
+Write `{backlog_path}` (default: `pipeline-backlog.yaml`):
+
+```yaml
+# Pipeline Backlog
+# Generated by v3-setup-backlog from {source document name}
+# Priority: lower number = higher priority
+
+items:
+  - id: "KANBAN-001"
+    type: story
+    status: pending
+    priority: 1
+    epic: "KANBAN-MVP"
+    title: "Create a new card via the API"
+    depends_on: []
+
+  - id: "KANBAN-002"
+    type: story
+    status: pending
+    priority: 2
+    epic: "KANBAN-MVP"
+    title: "Fetch all cards grouped by status"
+    depends_on: ["KANBAN-001"]
+
+  # ... more stories
+```
+
+## Step 6: Write Story Input Files
+
+For each story, create `{story_directory}/{story-id}/story.md`:
+
+```markdown
+# {Story Title}
+
+## User Story
+
+As a {role} I want {capability} so that {benefit}.
+
+## Acceptance Criteria
+
+### AC-1: {short name}
+**Given** {precondition}
+**When** {action}
+**Then** {expected outcome}
+
+### AC-2: {short name}
+**Given** {precondition}
+**When** {action}
+**Then** {expected outcome}
+
+{additional ACs...}
+
+## Notes
+
+{Any architecture notes, UX references, or constraints from the source document}
+```
+
+**AC formatting rules:**
+- Each AC gets an ID (`AC-1`, `AC-2`, ...) — the pipeline references these throughout
+- Convert bullet-point ACs to Given-When-Then format
+- Keep them testable — every AC must be verifiable by automated tests
+- If an AC is vague ("the UI should look good"), flag it and ask the user to clarify or remove it
+- Include error/edge cases as separate ACs, not just happy paths
+
+## Step 7: Initialize Knowledge Base
+
+Scan the repo to build the curated knowledge files that the Knowledge Agent uses at runtime. Write these to `knowledge/curated/`:
+
+### `project-context.md`
+Scan the repo and generate:
+- Project name and purpose (from README, package.json, or ask the user)
+- Directory layout (top-level structure)
+- Tech stack (from `v3/pipeline-config.yaml` + detected from package.json, tsconfig, etc.)
+- Database schema (from Prisma schema, migrations, or SQL files if present)
+- Existing API endpoints (from route files if present)
+- Environment setup (from docker-compose, Dockerfile, .env.example if present)
+
+### `code-conventions.md`
+Scan existing source code and extract:
+- Import patterns (ESM vs CJS, path aliases)
+- Naming conventions (camelCase, snake_case, file naming)
+- Project structure patterns (routes, services, controllers, etc.)
+- Test file organization and patterns
+- Error handling patterns
+- Any linting config (.eslintrc, .prettierrc, biome.json)
+
+### `api-reference.md` (if API endpoints exist)
+Scan route files and generate:
+- Method, path, request/response shapes
+- Validation rules
+- Auth requirements
+- Status codes
+
+If the repo is empty or brand new (no source code yet), create minimal placeholder files noting "No existing code detected — Knowledge Agent will update these as stories ship."
+
+## Step 8: Report
+
+After writing all files, summarize:
+
+```
+Created:
+  - {backlog_path} ({N} stories)
+  - {N} story input files in {story_directory}/
+  - knowledge/curated/project-context.md
+  - knowledge/curated/code-conventions.md
+  - knowledge/curated/api-reference.md (if applicable)
+
+Next steps:
+  - Review story files and refine ACs if needed
+  - Review knowledge/curated/ files for accuracy
+  - Run /v3-run-story {first-story-id} to start
+  - Or run /v3-run-epic {epic-id} to run the whole epic
+```
+
+## Rules
+
+- **Always ask for confirmation** before writing files (Step 4)
+- **Preserve the user's story IDs** if they exist — don't rename them
+- **Flag ambiguous ACs** — better to ask than to generate untestable criteria
+- **Don't invent stories** — only create what's in the source document
+- **Don't modify existing backlog entries** — if `pipeline-backlog.yaml` already has items, append new ones after the existing highest priority number