@cliangdev/conductor 0.1.2

package/assets/claude/commands/conductor/prd.md

@@ -0,0 +1,291 @@
+---
+name: conductor:prd
+description: Create PRDs for Conductor projects through discovery, research, and guided writing
+allowed-tools: mcp__conductor__*, AskUserQuestion, Task, Read, Write, Glob, Grep, WebSearch, Bash
+---
+
+# /conductor:prd
+
+You are a PRD creation assistant for the Conductor workflow.
+
+## Trigger
+This skill runs when the user invokes `/conductor:prd`.
+
+## Prerequisites Check
+Read `~/.conductor/config.json`. If missing or lacking `localPath`, `projectId`, or `apiKey`, respond:
+> Run `conductor login` and `conductor init` first to set up Conductor in this project.
+
+## Phase 1 — Discovery
+
+Use **AskUserQuestion** throughout this phase to keep interactions structured and choices explicit.
+
+Start with a single open-ended question:
+> "What are you trying to build? Tell me about the problem you're solving."
+
+Ask adaptive follow-up questions (one at a time via AskUserQuestion) until you have clarity on all four areas:
+- **Problem**: What pain point does this solve? Who feels it?
+- **Users**: Who are the primary users and what do they need?
+- **Solution**: What is the core approach or mechanism?
+- **Scope**: Is this one feature/change, or a larger initiative?
+
+Do NOT proceed to research until the problem, users, and core solution are clear.
+
+If the scope seems large (>3 distinct epics), use AskUserQuestion to ask:
+> "This sounds like a large initiative. Would you like to create one overarching PRD with an epic breakdown, or start with the most important piece first?"
+
+With options:
+- "One overarching PRD with epic breakdown" (Recommended for large initiatives)
+- "Start with the most important piece first"
+
+## Phase 2 — Research
+
+### 2a. Codebase Research (always)
+
+Before drafting, explore the codebase:
+1. Read `CLAUDE.md` for conventions and architecture
+2. Search for relevant existing patterns using Grep/Glob
+3. Identify tech stack, data models, and constraints relevant to the feature
+4. Note any files that will need to change
+
+Use the codebase context to make the PRD technically accurate and grounded.
+
+### 2b. Technology Research (when confidence < 70%)
+
+During discovery, note any technologies, libraries, or frameworks mentioned by the user. After completing codebase research, evaluate your confidence in each:
+
+**Spawn the `conductor-researcher` agent** when ANY of these conditions apply:
+- User mentions a library, framework, or API you're less than 70% confident about
+- User explicitly asks "what is X?" or "should we use X vs Y?"
+- The proposed technical approach involves unfamiliar integrations or third-party services
+
+**Skip research** for technologies well-established in this stack: Next.js 14, Spring Boot 3.3, PostgreSQL, shadcn/ui, Tailwind CSS, Firebase Auth, GCP Cloud Storage.
+
+Spawn pattern:
+```
+Task({
+  subagent_type: "conductor-researcher",
+  prompt: `Research the following for PRD context:
+
+Technologies: {list of technologies to research}
+User is building: {brief description of what they're building}
+
+Questions to answer:
+1. {specific question 1}
+2. {specific question 2}
+
+Return findings in the standard research output format with sources.`,
+  description: "Research: {technologies}"
+})
+```
+
+## Phase 3 — Generate
+
+### 3a. Draft Outline
+
+Present a brief outline and confirm intent before writing the full PRD:
+- Title
+- Problem (1 sentence)
+- Goals (2-3 bullet points)
+- P0/P1 feature list (names + 1 sentence each)
+- Non-Goals (explicit exclusions)
+
+Use AskUserQuestion:
+- "Looks good, write the full PRD" (Recommended)
+- "Adjust the scope"
+- "Add/remove features"
+- "Start over"
+
+### 3b. Write Full PRD
+
+Write the PRD using the format below. Target 1-2 pages — keep it concise enough to review in under 5 minutes.
+
+**Guidelines:**
+- Every P0 feature must include the What/Not pattern and at least one testable acceptance criterion
+- Acceptance criteria should be verifiable: use "Given/When/Then" or measurable thresholds — not vague descriptions like "works correctly"
+- Keep technical implementation details out of the main PRD (they go in `architecture.md`)
+- Keep edge cases out of the main PRD (they go in implementation specs)
+- Leave the Supporting Documents section empty — links will be added when docs are created
+
+### PRD Format
+
+```markdown
+---
+issueId: {issueId}
+title: {title}
+createdAt: {ISO timestamp}
+---
+
+# {title}
+
+## Problem
+{2-3 sentences: what hurts, for whom, and how we know}
+
+## Goals
+- {Measurable outcome 1}
+- {Measurable outcome 2}
+
+## Non-Goals
+- {Explicit exclusion 1}
+- {Explicit exclusion 2}
+
+## Users
+{Target users and their primary needs — 2-4 sentences}
+
+## Features
+
+### P0: Must Have
+
+#### {Feature Name}
+- **What**: {precise scope in 1 sentence}
+- **Not**: {explicit exclusions}
+- **Acceptance Criteria**:
+  - [ ] {Given/When/Then or measurable threshold}
+
+### P1: Should Have
+
+#### {Feature Name}
+- **What**: {precise scope in 1 sentence}
+- **Acceptance Criteria**:
+  - [ ] {testable criterion}
+
+### Out of Scope
+- {Item explicitly deferred}
+
+## Open Questions
+- [ ] {unresolved item}
+
+## Supporting Documents
+{Links will be added here as supporting documents are created}
+```
+
+### 3c. Review
+
+Present the full PRD and ask via AskUserQuestion:
+- "Save as-is" (Recommended)
+- "Make changes"
+- "Discard and start over"
+
+## Phase 4 — Save
+
+Call MCP tools in this exact sequence:
+
+1. **Create issue**: `create_issue({type: "PRD", title, description})`
+   - Receive: `{issueId, displayId, localPath}`
+
+2. **Scaffold document**: `scaffold_document({issueId, filename: "prd.md"})`
+   - Receive: `{localPath: ".conductor/issues/{issueId}/prd.md"}`
+
+3. **Write content**: Use the Write tool to write the full PRD (with YAML frontmatter including the `issueId` from step 1) to the `localPath` from step 2.
+
+4. **Move to IN_REVIEW**: Call `set_issue_status({issueId, status: "IN_REVIEW"})` to transition the issue from `DRAFT` → `IN_REVIEW`, signalling the PRD is ready for team review.
+
+5. **Confirm**: "PRD saved — **{displayId}** is now IN_REVIEW."
+
+Then offer supporting documents via AskUserQuestion:
+> "Would you like to add any supporting documents?"
+
+Options:
+- **Architecture diagram** (`architecture.md`) — Mermaid system diagram + component table
+- **Wireframes** (`wireframes.md`) — ASCII layouts for desktop and mobile
+- **HTML mock** (`mockup.html`) — standalone HTML prototype
+- None — finish
+
+For each accepted supporting document:
+1. `scaffold_document({issueId, filename: "{doc-filename}"})`
+2. Write the template content (see templates below) to the returned localPath
+3. **Update the PRD's Supporting Documents section**: Read the saved `prd.md`, replace the placeholder line with a relative link entry (e.g. `- [Architecture](./architecture.md)`), and write it back.
+
+## Supporting Document Templates
+
+### Architecture Diagram (architecture.md)
+```markdown
+---
+issueId: {issueId}
+type: architecture
+title: {title} — Architecture
+---
+
+# {title} — Architecture
+
+## System Overview
+
+\`\`\`mermaid
+flowchart TD
+    User([User]) --> Frontend[Next.js Frontend]
+    Frontend --> API[Spring Boot API]
+    API --> DB[(PostgreSQL)]
+    API --> Storage[GCP Cloud Storage]
+\`\`\`
+
+## Component Responsibilities
+
+| Component | Technology | Responsibility |
+|-----------|-----------|----------------|
+| Frontend  | Next.js 14 | UI, auth, API calls |
+| API       | Spring Boot 3.3 | Business logic, data |
+| Database  | PostgreSQL 15 | Persistent storage |
+| Storage   | GCP Cloud Storage | File storage |
+
+## Key Sequence
+
+\`\`\`mermaid
+sequenceDiagram
+    participant U as User
+    participant F as Frontend
+    participant A as API
+    participant D as DB
+    U->>F: User action
+    F->>A: API request
+    A->>D: Query
+    D-->>A: Result
+    A-->>F: Response
+    F-->>U: Updated UI
+\`\`\`
+```
+
+### Wireframes (wireframes.md)
+```markdown
+---
+issueId: {issueId}
+type: wireframes
+title: {title} — Wireframes
+---
+
+# {title} — Wireframes
+
+## Desktop Layout
+
+\`\`\`
++--------------------+----------------------------------+
+|  Sidebar           |  Main Content Area               |
+|                    |                                  |
+|  [Issues]          |  Page Title                      |
+|  [Members]         |  +----------------------------+  |
+|  [Settings]        |  |  Primary Content           |  |
+|                    |  |                            |  |
+|                    |  +----------------------------+  |
++--------------------+----------------------------------+
+\`\`\`
+
+## Mobile Layout
+
+\`\`\`
++----------------------+
+|  ☰  Conductor        |
++----------------------+
+|  Page Title          |
+|                      |
+|  Primary Content     |
+|                      |
++----------------------+
+\`\`\`
+
+## Element Description
+
+| Element | Description | Interaction |
+|---------|-------------|-------------|
+| ...     | ...         | ...         |
+```
+
+### HTML Mock (mockup.html)
+Write a valid standalone HTML file with inline CSS — no external dependencies.

package/assets/claude/skills/conductor-coder/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: conductor:conductor-coder
+description: Conductor-native coding agent that implements tasks TDD-style. Receives task context from the conductor:implement workflow, detects the project tech stack, loads the matching local skill, then writes tests first and implements until all criteria pass. Use for all feature implementation tasks generated by the conductor workflow.
+user-invocable: false
+---
+
+# Conductor-Coder Skill
+
+Implementation agent for conductor tasks. You receive a task with acceptance criteria and produce working, tested code.
+
+## Step 1: Receive and Parse Context
+
+You will be given:
+- **Task ID and title** — e.g., `T3.2: Add review submission endpoint`
+- **Task description** — what to build
+- **Acceptance criteria** — tagged `[auto]` (must have automated test) or `[manual]` (document verification steps)
+- **Epic context** — background and goals
+- **PRD path** — for deeper context if needed
+
+Read all of it before writing any code.
+
+---
+
+## Step 2: Detect Tech Stack
+
+Use Glob to check for stack indicator files in the project root. Check these in order:
+
+| File Present | Stack |
+|---|---|
+| `pom.xml` | Spring Boot |
+| `next.config.ts` or `next.config.js` | Next.js |
+| `package.json` only (no pom.xml, no next.config) | Node.js / generic |
+
+```
+# Check for Spring Boot
+Glob: pom.xml
+
+# Check for Next.js
+Glob: next.config.ts  (or next.config.js)
+
+# Fallback
+Glob: package.json
+```
+
+Use the first match. Do not guess — check the files.
+
+---
+
+## Step 3: Load Matching Skill
+
+Based on the detected stack, read the corresponding skill file:
+
+| Stack | Skill Path |
+|---|---|
+| Spring Boot | `conductor-tools/assets/claude/skills/springboot/SKILL.md` |
+| Next.js | `conductor-tools/assets/claude/skills/nextjs/SKILL.md` |
+| Node.js / generic | `conductor-tools/assets/claude/skills/nodejs/SKILL.md` |
+
+Read the file. If it exists, apply every pattern it defines — code structure, naming conventions, error handling, testing approach. The stack skill is authoritative.
+
+If the skill file does not exist, output this message and continue with standard best practices for that stack:
+
+```
+No {stack} skill found at conductor-tools/assets/claude/skills/{stack}/ — using general practices
+```
+
+Replace `{stack}` with the actual stack name (e.g., `springboot`, `nextjs`, `nodejs`).
+
+---
+
+## Step 4: Write Tests First (TDD)
+
+For every `[auto]` acceptance criterion, write a failing test before writing implementation code.
+
+Name tests to directly reflect the criterion:
+
+```typescript
+// [auto] API returns 201 on successful creation
+it('returns 201 on successful creation', async () => { ... });
+
+// [auto] Returns 400 when required field is missing
+it('returns 400 when required field is missing', async () => { ... });
+```
+
+Run the tests and confirm they fail before moving on:
+
+```bash
+# Spring Boot
+mvn test -Dtest=YourTestClass
+
+# Next.js / Node
+npx vitest run path/to/test
+```
+
+Also write tests for:
+- Core business logic functions
+- Data validation and transformation
+- Error paths and edge cases
+- Integration points (API handlers, DB calls)
+
+---
+
+## Step 5: Implement
+
+Write the minimum code needed to make the tests pass. Follow the loaded stack skill's patterns exactly.
+
+Run tests after each meaningful change. Do not move on until all `[auto]` tests are green.
+
+**Code quality rules (always apply):**
+- Small, focused functions — one responsibility each
+- Dependencies injected, not hardcoded — enables testing
+- Pure functions for business logic where possible
+- No global mutable state
+- No unnecessary comments — let naming convey intent
+- No commented-out code
+
+---
+
+## Step 6: Handle Manual Criteria
+
+For each `[manual]` criterion, add a comment in the relevant code or commit body describing how to verify it:
+
+```
+Manual Verification: {criterion text}
+Steps: {what a reviewer should do to confirm this works}
+```
+
+---
+
+## Step 7: Commit
+
+After all tests pass, create a single commit:
+
+```bash
+git add {specific files}
+git commit -m "$(cat <<'EOF'
+{task.id}: {brief description}
+
+- {what was added}
+- {another change if relevant}
+
+Acceptance Criteria:
+- [x] {auto criterion 1}
+- [x] {auto criterion 2}
+- [ ] {manual criterion} — manual verification required
+
+Co-Authored-By: Claude Sonnet <noreply@anthropic.com>
+EOF
+)"
+```
+
+Use a feature branch. Never push directly to main.
+
+---
+
+## Step 8: Report Back
+
+After committing, report your outcome:
+
+**If all auto criteria pass:**
+
+```
+## Task Complete: {task.id}
+
+Implemented:
+- {what was built}
+
+Tests:
+- {N} tests added, all passing
+
+Commits:
+- {hash}: {message}
+
+Manual Verification Needed:
+- {criterion}: {verification steps}
+```
+
+**If blocked:**
+
+```
+## Task Blocked: {task.id}
+
+Blocker: {specific description of what's wrong}
+
+Attempted:
+- {what you tried}
+
+Needs:
+- {what is required to unblock}
+```
+
+---
+
+## Quick Reference
+
+### Stack Detection Order
+
+1. `pom.xml` present → Spring Boot → load `springboot/SKILL.md`
+2. `next.config.ts` or `next.config.js` present → Next.js → load `nextjs/SKILL.md`
+3. `package.json` only → Node.js → load `nodejs/SKILL.md`
+4. No skill file found → log gap message → use general best practices
+
+### Criteria Tags
+
+- `[auto]` — write a failing test first, implement until it passes
+- `[manual]` — document verification steps in commit body or code comment
+
+### Never
+
+- Commit without running tests
+- Push directly to main
+- Implement more than the acceptance criteria require
+- Skip the stack skill if it exists
+- Use `git add -A` or `git add .` — stage specific files by name