opencodekit 0.16.15 → 0.16.17

package/dist/template/.opencode/command/create.md

@@ -6,364 +6,132 @@ agent: build
 
 # Create: $ARGUMENTS
 
-Create a bead and its artifacts from a description. Auto-classifies bead type based on keywords.
+Create a bead and its specification (PRD) from a description.
 
-> **Lifecycle context:** Ideation → Design → **Specification** → Task Conversion → Planning → Implementation → Verification
+> **Workflow:** **`/create`** → `/start <id>` → `/ship <id>`
 >
-> **Workflow:** `/create` → `/start <id>` → `/ship <id>` → `/verify <id>`
-
-## Parse Arguments
-
-| Argument        | Default       | Description                                |
-| --------------- | ------------- | ------------------------------------------ |
-| `<description>` | required      | What you want to build/fix (quoted string) |
-| `--type`        | auto-detected | Override type: epic, feature, task, bug    |
+> ⛔ This command creates the specification ONLY. Do NOT write any implementation code.
 
 ## Load Skills
 
 ```typescript
-skill({ name: "development-lifecycle" }); // Phase guidance
 skill({ name: "beads" });
 skill({ name: "prd" }); // PRD template guidance
-skill({ name: "memory-system" });
-```
-
-## Check Memory First
-
-Search for similar specs and patterns before creating:
-
-```typescript
-// Find similar past specs
-memory_search({ query: "[description keywords]", limit: 3 });
-
-// Find related patterns and conventions
-memory_search({ query: "[domain keywords] spec requirements", limit: 3 });
-```
-
-Review findings for:
-
-- Similar specs that worked well (reuse structure)
-- Patterns and conventions already established
-- Gotchas to avoid in this domain
-
----
-
-## Phase 1: Classify Bead Type
-
-**Auto-classification based on description keywords:**
-
-| Keywords in Description                                         | Classified As |
-| --------------------------------------------------------------- | ------------- |
-| "redesign", "overhaul", "migrate", "new system", "platform"     | `epic`        |
-| "add", "implement", "create", "build", "new feature", "support" | `feature`     |
-| "fix", "bug", "broken", "error", "crash", "issue", "failing"    | `bug`         |
-| Default (none of above)                                         | `task`        |
-
-```typescript
-function classifyBeadType(description: string): "epic" | "feature" | "task" | "bug" {
-  const desc = description.toLowerCase();
-
-  // Epic indicators (large scope)
-  if (/redesign|overhaul|migrate|new system|platform|architecture/.test(desc)) {
-    return "epic";
-  }
-
-  // Bug indicators
-  if (/fix|bug|broken|error|crash|issue|failing|doesn't work|not working/.test(desc)) {
-    return "bug";
-  }
-
-  // Feature indicators
-  if (/add|implement|create|build|new feature|support|enable|integrate/.test(desc)) {
-    return "feature";
-  }
-
-  // Default to task
-  return "task";
-}
-```
-
-**User can override with `--type` flag.**
-
----
-
-## Phase 2: Create Bead
-
-```bash
-# Create the bead with classified type
-BEAD_ID=$(br create "$DESCRIPTION" --type $BEAD_TYPE --json | jq -r '.id')
-echo "Created bead: $BEAD_ID"
 ```
 
----
-
-## Phase 3: Setup Artifact Directory
+## Parse Arguments
 
-```bash
-BEAD_DIR=".beads/artifacts/$BEAD_ID"
-mkdir -p "$BEAD_DIR"
-```
+| Argument        | Default       | Description                        |
+| --------------- | ------------- | ---------------------------------- |
+| `<description>` | required      | What to build/fix (quoted string)  |
+| `--type`        | auto-detected | Override: epic, feature, task, bug |
 
 ---
 
-## Phase 4: Choose Artifacts (Auto-Detection)
-
-**Artifact selection based on bead type:**
-
-| Bead Type | Auto-Created             | Rationale                            |
-| --------- | ------------------------ | ------------------------------------ |
-| `epic`    | `proposal.md` + `prd.md` | Major work needs high-level proposal |
-| `feature` | `proposal.md` + `prd.md` | Scoped work benefits from proposal   |
-| `task`    | `prd.md`                 | Tactical work, skip proposal         |
-| `bug`     | `prd.md`                 | Clear problem, skip proposal         |
+## Phase 1: Duplicate Check
 
 ```bash
-# Determine if proposal is needed
-NEEDS_PROPOSAL=false
-if [ "$BEAD_TYPE" = "epic" ] || [ "$BEAD_TYPE" = "feature" ]; then
-  NEEDS_PROPOSAL=true
-fi
-
-# Always create PRD
-cp .opencode/memory/_templates/prd.md "$BEAD_DIR/prd.md"
-
-# Create proposal if needed (epic/feature)
-if [ "$NEEDS_PROPOSAL" = "true" ]; then
-  cp .opencode/memory/_templates/proposal.md "$BEAD_DIR/proposal.md"
-fi
+br list --status=open --status=in_progress
 ```
 
----
-
-## Phase 5: Gather Context for Spec
-
-### Ask Clarifying Questions (if needed)
-
-If description is vague, ask for more details:
-
-```typescript
-question({
-  questions: [
-    {
-      header: "Scope",
-      question: "What should this feature do? Describe the core functionality.",
-      options: [], // Free text
-    },
-    {
-      header: "Users",
-      question: "Who will use this? (developers, end users, API consumers, etc.)",
-      options: [
-        { label: "Developers", description: "Internal tooling or API" },
-        { label: "End users", description: "Customer-facing feature" },
-        { label: "Both", description: "Used by developers and users" },
-      ],
-    },
-    {
-      header: "Constraints",
-      question: "Any constraints? (performance, compatibility, security)",
-      options: [], // Free text
-    },
-  ],
-});
-```
-
-### Research Existing Patterns (Optional)
-
-If user provides enough context, delegate to explore agent:
-
-```typescript
-Task({
-  subagent_type: "explore",
-  description: "Find similar patterns",
-  prompt: `Find patterns in codebase related to: [description]
-    - Similar implementations
-    - Existing conventions
-    - Test patterns used
-    Return: File paths and patterns found`,
-});
-```
-
----
-
-## Phase 6: Fill In Template
-
-### For prd.md
+If a matching bead exists, stop and tell the user to use `/start <id>` instead.
 
-Fill in the PRD template with goal, scope, and tasks:
+## Phase 2: Classify Type
 
-```markdown
-# Beads PRD Template
+If `--type` was provided, use it directly. Otherwise, suggest a type based on the description and ask the user to confirm:
 
-**Bead:** $BEAD_ID
-**Created:** [today]
-**Status:** Draft
+- **epic**: Multi-session, cross-domain (redesign, migrate, overhaul)
+- **feature**: New capability, scoped (add, implement, build, integrate)
+- **bug**: Something broken (fix, error, crash, not working)
+- **task**: Tactical change, clear scope (everything else)
 
-## Goal
+## Phase 3: Gather Context
 
-[From description and clarifying questions]
+Spawn parallel subagents to understand the codebase before writing any spec:
 
-## Scope
+| Agent                       | Purpose                             | Returns                               |
+| --------------------------- | ----------------------------------- | ------------------------------------- |
+| `explore`                   | Affected files and patterns         | File paths, conventions, architecture |
+| `explore`                   | Test patterns and coverage gaps     | Test files, patterns, gaps            |
+| `explore`                   | Dependencies and integration points | Dependency graph, risk areas          |
+| `scout` (feature/epic only) | Best practices and approaches       | Recommendations, warnings             |
+| `review` (epic only)        | Architecture impact                 | Breaking changes, decomposition       |
 
-### In-Scope
+All agents launch in ONE message — they run concurrently.
 
-- [From user input]
+**While agents run**, ask clarifying questions if the description lacks scope or expected outcome. For bugs, also ask for reproduction steps and expected vs actual behavior. Skip questions if the description is already specific.
 
-### Out-of-Scope
-
-- [Explicitly excluded]
-
-## Success Criteria
-
-- [ ] [Measurable criterion]
-  - Verify: `[command]`
-
-## Tasks
-
-### [Task Title] [category]
-
-[End state description]
-
-**Verification:**
-
-- [Command or check]
-```
-
-### For proposal.md (epic/feature)
-
-Fill in high-level proposal first:
-
-```markdown
-# Proposal: [Title]
-
-**Bead:** $BEAD_ID
-**Date:** [today]
-
-## Problem Statement
-
-[What problem are we solving?]
-
-## Proposed Solution
-
-[High-level approach]
-
-## Scope
-
-### In-Scope
-
-- [Major deliverable]
-
-### Out-of-Scope
-
-- [Explicitly excluded]
-
-## Timeline
-
-| Phase   | Duration | Deliverables |
-| ------- | -------- | ------------ |
-| Phase 1 | X weeks  | ...          |
-
-## Risks
-
-| Risk | Likelihood | Impact | Mitigation |
-| ---- | ---------- | ------ | ---------- |
-| ...  | ...        | ...    | ...        |
-```
-
----
-
-## Phase 7: Validate PRD
-
-Before saving, validate the PRD:
-
-- [ ] Goal is clear and measurable?
-- [ ] Success criteria have verification commands?
-- [ ] Tasks have end state descriptions (not steps)?
-- [ ] Out of scope is defined?
-- [ ] Dependencies identified (if any)?
-
-If validation fails, ask user for missing information.
-
----
-
-## Phase 8: Save and Report
-
-Save the filled template to the bead artifacts folder.
+## Phase 4: Create Bead
 
 ```bash
-# Verify files were created
-ls -la "$BEAD_DIR/"
+BEAD_ID=$(br create "$DESCRIPTION" --type $BEAD_TYPE --json | jq -r '.id')
+mkdir -p ".beads/artifacts/$BEAD_ID"
 ```
 
-Update bead with note:
+## Phase 5: Write PRD
+
+Copy and fill the PRD template using context from Phase 3:
 
 ```bash
-br comments add $BEAD_ID "Created prd.md with [N] tasks defined"
+cp .opencode/memory/_templates/prd.md ".beads/artifacts/$BEAD_ID/prd.md"
 ```
 
-## Record Learning (If Significant)
+### Required Sections
 
-If you discovered patterns or made decisions worth remembering:
+| Section           | Source                                                     | Required          |
+| ----------------- | ---------------------------------------------------------- | ----------------- |
+| Problem Statement | User description + clarifying questions                    | Always            |
+| Scope (In/Out)    | User input + codebase exploration                          | Always            |
+| Proposed Solution | Codebase patterns + user intent                            | Always            |
+| Success Criteria  | User verification + test commands (must include `Verify:`) | Always            |
+| Technical Context | Explore agent findings                                     | Always            |
+| Affected Files    | Explore agent findings (real paths from Phase 3)           | Always            |
+| Tasks             | Derived from scope + solution                              | Always            |
+| Risks             | Codebase exploration                                       | Feature/epic only |
+| Open Questions    | Unresolved items from Phase 3                              | If any exist      |
 
-```typescript
-observation({
-  type: "pattern", // or "decision"
-  title: "[Domain] spec pattern for [type of feature]",
-  narrative: "When creating specs for [this type], include...",
-  concepts: "[domain keywords]",
-  bead_id: "$BEAD_ID",
-  confidence: "medium",
-});
-```
+### Task Format
 
----
+Tasks must follow the `prd-task` skill format:
 
-## Output
+- Title with `[category]` tag
+- One-sentence **end state** description (not step-by-step)
+- Metadata block: `depends_on`, `parallel`, `conflicts_with`, `files`
+- At least one verification command per task
 
-```
-Created: $BEAD_ID
-━━━━━━━━━━━━━━━━━━━
+## Phase 6: Validate PRD
 
-Description: [original description]
-Type: [classified type] (auto-detected | --type override)
+Before saving, verify:
 
-Artifacts:
-├── .beads/artifacts/$BEAD_ID/prd.md [NEW]
-└── .beads/artifacts/$BEAD_ID/proposal.md [if epic/feature]
+- [ ] No placeholder text remains (e.g., "[Clear description", "[List what's allowed]")
+- [ ] Success criteria include `Verify:` commands
+- [ ] Technical context references actual `src/` paths from exploration
+- [ ] Affected files list real paths
+- [ ] Tasks have `[category]` headings
+- [ ] Each task has verification
+- [ ] No implementation code in the PRD
 
-Tasks: [N] defined
-Success Criteria: [N] with verification
+If any check fails, fix it — don't ask the user.
 
-Next: /plan $BEAD_ID (convert PRD to implementation plan)
-      /start $BEAD_ID (if simple, skip planning)
-```
+## Phase 7: Report
 
----
+Output:
 
-## Examples
+1. Bead ID and type
+2. PRD location (`.beads/artifacts/$BEAD_ID/prd.md`)
+3. Summary: task count, success criteria count, affected files count
+4. Next steps: `/start $BEAD_ID` or `/plan $BEAD_ID`
 
 ```bash
-# Auto-classified as 'feature' (creates proposal + prd)
-/create "Add user authentication with OAuth"
-
-# Auto-classified as 'bug' (creates prd only)
-/create "Fix login page not loading on mobile"
-
-# Auto-classified as 'epic' (creates proposal + prd)
-/create "Redesign the entire dashboard UI"
-
-# Auto-classified as 'task' (creates prd only)
-/create "Update dependencies to latest versions"
-
-# Override type explicitly
-/create "Refactor auth module" --type feature
+br comments add $BEAD_ID "Created prd.md with [N] tasks, [M] success criteria"
 ```
 
 ---
 
 ## Related Commands
 
-| Need            | Command              |
-| --------------- | -------------------- |
-| Research first  | `/research $BEAD_ID` |
-| Plan after spec | `/plan $BEAD_ID`     |
-| Start working   | `/start $BEAD_ID`    |
+| Need            | Command       |
+| --------------- | ------------- |
+| Research first  | `/research`   |
+| Plan after spec | `/plan <id>`  |
+| Start working   | `/start <id>` |