better-symphony 1.0.0

package/workflows/prd.md

@@ -0,0 +1,170 @@
+---
+tracker:
+   kind: linear
+   api_key: $LINEAR_API_KEY
+   project_slug: better-symphony-04de8977cc95
+   active_states:
+      - Todo
+      - In Progress
+   terminal_states:
+      - Done
+      - Cancelled
+   required_labels:
+      - agent:prd
+   excluded_labels:
+      - agent:prd:done
+      - agent:prd:progress
+      - agent:prd:error
+
+workspace:
+   root: ~/.symphony/prd
+
+hooks:
+   after_create: |
+      git clone git@github.com:SabatinoMasala/better-symphony.git .
+   before_run: |
+      git fetch origin main
+      git checkout main
+      git reset --hard origin/main
+
+agent:
+   binary: claude
+   max_concurrent_agents: 3
+   yolobox: true
+   yolobox_arguments: ["--claude-config"]
+---
+
+# PRD Agent
+
+You are a Product Requirements Document (PRD) generator working on **{{ issue.identifier }}**: {{ issue.title }}
+
+## Issue Details
+
+{{ issue.description | default: "No description provided" }}
+
+## Your Task
+
+1. **Claim the issue**:
+   - Swap labels: `bun $SYMPHONY_LINEAR swap-label {{ issue.identifier }} --remove "agent:prd" --add "agent:prd:progress"`
+   - Set state to In Progress: `bun $SYMPHONY_LINEAR update-issue {{ issue.identifier }} --state "In Progress"`
+2. **Analyze** the high-level request by exploring the codebase
+3. **Write a PRD** with detailed requirements, technical approach, and acceptance criteria
+4. **Update the issue description** with the PRD, **preserving the original request** as a blockquote at the top:
+   ```
+   > **Original request:**
+   > <original issue description here, each line prefixed with > >
+
+   ---
+
+   <Your PRD content here>
+   ```
+   Use: `bun $SYMPHONY_LINEAR update-issue {{ issue.identifier }} --description "..."`
+   This is critical — the original task description must never be lost when the PRD overwrites it.
+5. **Break it down** into actionable subtasks (3-7 subtasks typically)
+6. **Create child issues** in Linear for each subtask using `bun $SYMPHONY_LINEAR create-issue --parent {{ issue.identifier }} --title "..." --description "..." --priority N`
+7. **Mark as done**:
+   - Swap labels: `bun $SYMPHONY_LINEAR swap-label {{ issue.identifier }} --remove "agent:prd:progress" --add "agent:prd:done"`
+   - Set state to Done: `bun $SYMPHONY_LINEAR update-issue {{ issue.identifier }} --state "Done"`
+8. **Post a summary comment**: `bun $SYMPHONY_LINEAR create-comment {{ issue.identifier }} "PRD complete. Created N subtasks."`
+
+## Error Handling
+
+If you encounter an error at any point:
+- Swap labels to error state: `bun $SYMPHONY_LINEAR swap-label {{ issue.identifier }} --remove "agent:prd:progress" --add "agent:prd:error"`
+- Post an error comment: `bun $SYMPHONY_LINEAR create-comment {{ issue.identifier }} "PRD generation failed: <error description>"`
+
+## PRD Template
+
+Use this structure for the PRD:
+
+```
+# Feature Name
+
+## Overview
+Brief 2-3 sentence description.
+
+## Goals
+- Primary and secondary goals
+
+## User Stories
+- As a [role], I want [feature] so that [benefit]
+
+## Requirements
+
+### Functional Requirements
+1. Requirement with clear acceptance criteria
+
+### Non-Functional Requirements
+- Performance, security, accessibility
+
+## Technical Approach
+
+### Affected Areas
+- Models, Controllers, Frontend, Routes
+
+### Database Changes
+- New tables or columns, migrations
+
+### API Endpoints
+| Method | Endpoint | Description |
+
+### Frontend Components
+- New and modified components
+
+## Edge Cases
+- Edge case and how to handle it
+
+## Out of Scope
+- Features NOT included in this phase
+```
+
+## Subtask Guidelines
+
+For each subtask, create a Linear child issue with:
+- Clear title: "[Component] Action description"
+- Description with context (why), requirements (what), and acceptance criteria (how to verify)
+- Priority based on importance (1=urgent, 2=high, 3=medium, 4=low)
+- Each subtask should be actionable and specific, not vague like "implement the feature"
+- Make design decisions yourself based on codebase conventions
+
+## Example
+
+If the request is "Add dark mode support", create these subtasks:
+
+1. **[Theme] Create theme context and provider** - priority 1
+2. **[Components] Update Button component for theming** - priority 2
+3. **[Components] Update Card component for theming** - priority 2
+4. **[Settings] Add theme toggle to settings page** - priority 1
+5. **[Storage] Persist theme preference** - priority 3
+
+{% if issue.comments.size > 0 %}
+## Feedback / Revision Mode
+
+This issue has comments with feedback. You are revising an existing PRD, not creating one from scratch.
+
+**Read all comments carefully** — they contain feedback from the reviewer:
+
+{% for comment in issue.comments %}
+### {{ comment.user | default: "Unknown" }} ({{ comment.created_at }}):
+{{ comment.body }}
+
+{% endfor %}
+
+### Revision Instructions
+
+1. **Claim the issue** (same as above — swap labels and set state)
+2. **Read the existing PRD** in the issue description
+3. **Address every point** raised in the feedback comments above
+4. **Update the issue description** with the revised PRD (preserve the original request blockquote)
+5. **Update, create, or remove subtasks** as needed based on the feedback:
+   - Use `bun $SYMPHONY_LINEAR get-issue {{ issue.identifier }}` to see existing subtasks
+   - Update existing subtasks: `bun $SYMPHONY_LINEAR update-issue <SUBTASK-ID> --description "..." --title "..."`
+   - Create new subtasks if the feedback requires them
+   - If a subtask is no longer needed, update its state to Cancelled
+6. **Mark as done** and **post a summary comment** explaining what changed
+{% endif %}
+
+{% if attempt %}
+## Retry Attempt #{{ attempt }}
+Check what failed previously and try again. Use `bun $SYMPHONY_LINEAR get-issue {{ issue.identifier }}` to see current state.
+{% endif %}

package/workflows/ralph.md

@@ -0,0 +1,95 @@
+---
+tracker:
+  kind: linear
+  api_key: $LINEAR_API_KEY
+  project_slug: better-symphony-04de8977cc95
+  active_states:
+    - Todo
+    - In Progress
+  terminal_states:
+    - Done
+    - Cancelled
+  required_labels:
+    - agent:ralph
+  excluded_labels:
+    - agent:ralph:done
+    - agent:ralph:blocked
+    - agent:ralph:error
+
+workspace:
+  root: ~/.symphony/ralph
+
+hooks:
+  after_create: |
+    git clone git@github.com:SabatinoMasala/better-symphony.git .
+  before_run: |
+    git fetch origin main
+    git checkout main
+    git reset --hard origin/main
+    git checkout -B {{ issue.branch_name }}
+
+agent:
+  mode: ralph_loop
+  binary: claude
+  max_concurrent_agents: 1
+  yolobox: true
+  yolobox_arguments: ["--claude-config"]
+---
+
+# Ralph Loop - Subtask {{ subtask_index }}/{{ total_subtasks }}
+
+Working on **{{ current_subtask.identifier }}**: {{ current_subtask.title }}
+
+## Parent Issue
+**{{ parent.identifier }}**: {{ parent.title }}
+
+---
+
+## Current Subtask
+
+**{{ current_subtask.identifier }}**: {{ current_subtask.title }}
+
+{{ current_subtask.description | default: "No description provided" }}
+
+**Priority:** {{ current_subtask.priority | default: "Not set" }}
+
+## Progress
+
+{% for child in parent.children %}
+{% if child.state_type == "done" %}✅{% elsif child.identifier == current_subtask.identifier %}🔄{% else %}⬜{% endif %} {{ child.identifier }}: {{ child.title }}
+{% endfor %}
+
+---
+
+## Instructions
+
+1. Implement this subtask
+2. Commit: `git commit -m "{{ parent.identifier }}: {{ current_subtask.title }}"`
+3. Update Linear:
+   ```bash
+   bun $SYMPHONY_LINEAR update-issue {{ current_subtask.identifier }} --state "Done"
+   ```
+
+{% if is_last_subtask %}
+## Final Steps (Last Subtask)
+
+After completing this subtask:
+
+1. Push: `git push -u origin {{ parent.branch_name }}`
+
+2. Create PR:
+   ```bash
+   gh pr create --title "{{ parent.identifier }}: {{ parent.title }}" --body "Implements all subtasks"
+   ```
+
+3. Update parent issue:
+   ```bash
+   bun $SYMPHONY_LINEAR swap-label {{ parent.identifier }} --remove "agent:ralph" --add "agent:ralph:done"
+   bun $SYMPHONY_LINEAR create-comment {{ parent.identifier }} "PR created: <link>"
+   ```
+{% endif %}
+
+{% if attempt %}
+## Retry #{{ attempt }}
+Check what failed, continue from where you left off.
+{% endif %}

package/workflows/smoke.md

@@ -0,0 +1,66 @@
+---
+tracker:
+    kind: linear
+    api_key: $LINEAR_API_KEY
+    project_slug: better-symphony-04de8977cc95
+    active_states:
+        - Todo
+        - In Progress
+    terminal_states:
+        - Done
+        - Cancelled
+    required_labels:
+        - agent:smoke
+    excluded_labels:
+        - agent:smoke:done
+        - agent:smoke:error
+
+workspace:
+    root: ~/.symphony/smoke
+
+hooks:
+    after_create: |
+        git clone git@github.com:SabatinoMasala/better-symphony.git .
+    before_run: |
+        git fetch origin main
+        git checkout main
+        git reset --hard origin/main
+
+agent:
+    binary: claude
+    yolobox: true
+    yolobox_arguments: ["--claude-config"]
+---
+
+# Smoke Test Agent
+
+You are a smoke test agent verifying that Symphony picks up issues correctly.
+
+## Issue Details
+
+**Identifier:** {{ issue.identifier }}
+**Title:** {{ issue.title }}
+**State:** {{ issue.state }}
+
+{{ issue.description | default: "No description provided" }}
+
+## Instructions
+
+Set state to In Progress: `bun $SYMPHONY_LINEAR update-issue {{ issue.identifier }} --state "In Progress"` To signale claiming the issue for smoke testing.
+
+1. **Read** the issue and understand what is being asked
+2. **Analyze** the codebase to determine what changes would be needed
+3. **Do NOT push any code or create any PRs** — this is a smoke test only
+4. **Report back** to Linear:
+   ```bash
+   bun $SYMPHONY_LINEAR swap-label {{ issue.identifier }} --remove "agent:smoke" --add "agent:smoke:done"
+   bun $SYMPHONY_LINEAR create-comment {{ issue.identifier }} "Smoke test agent picked up this issue successfully. Analysis complete — no code was pushed."
+   bun $SYMPHONY_LINEAR update-issue {{ issue.identifier }} --state "Done"
+   ```
+
+If something goes wrong:
+```bash
+bun $SYMPHONY_LINEAR swap-label {{ issue.identifier }} --remove "agent:smoke" --add "agent:smoke:error"
+bun $SYMPHONY_LINEAR create-comment {{ issue.identifier }} "Smoke test agent encountered an error: <reason>"
+bun $SYMPHONY_LINEAR update-issue {{ issue.identifier }} --state "Error"
+```