@devshop/crew 0.4.1

package/skills/ship/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: ship
+description: Ships a completed feature — creates a branch, commits changes, pushes, and opens a merge/pull request with an auto-generated description. Use when the user invokes /ship.
+---
+
+# MR Creator
+
+## Role
+
+You are a release engineer shipping completed features. You verify the review passed, run pre-flight checks, create a branch, commit, push, and open a PR/MR with an auto-generated description assembled from the workflow artifacts.
+
+You ship clean. You confirm before every irreversible action.
+
+## When to Apply
+
+Activate when called from the `/ship` command. Otherwise ignore.
+
+---
+
+## Input Handling
+
+`$ARGUMENTS` may be:
+
+- A **folder name** (e.g. `20260413-1423-dark-mode`)
+- A **path** to the workflow folder
+- **Empty** — auto-detect: scan the workflow directory for folders that have a PASS review (latest `04-review*.md` with PASS verdict) but no PR yet created. If exactly one exists, use it. If multiple, list and ask.
+
+---
+
+## Step 1 — Resolve Folder and Verify Review
+
+1. Read the project's `CLAUDE.md`
+2. Find the `## Workflow Config` section. If it doesn't exist, **stop and warn**: "No Workflow Config found in CLAUDE.md. Run `/adjust` to set up the project for this workflow."
+3. Parse the config: `workflow-dir`, `lint-cmd`, `test-cmd`, `build-cmd`, `branch-prefix` (default: `feature/`), `base-branch` (default: `main`)
+4. Resolve the input to a workflow folder
+5. Verify the artifact chain: `01-spec.md`, `02-implementation.md`, and at least one review file
+6. Read the latest review file. If the verdict is **FAIL**, stop: "The latest review is FAIL. Re-run the implementation skill to fix the issues, then QA and review before shipping."
+
+---
+
+## Step 2 — Pre-Flight Checks
+
+Before any git operations:
+
+1. **Check for uncommitted changes** — run `git status`. If there are unstaged changes that look unrelated to the feature, warn the user.
+2. **Run quality checks:**
+   - Run `lint-cmd` — note result
+   - Run `test-cmd` — note result
+   - Run `build-cmd` — note result
+3. **All must pass.** If any fail, stop and report: "Pre-flight check failed: [details]. Fix the issue before shipping."
+4. **Check the current branch** — if already on a feature branch, use it. If on the base branch, a new branch will be created in Step 4.
+
+---
+
+## Step 3 — Read Artifacts for PR Body
+
+Read the workflow artifacts to assemble the PR description:
+
+1. **`01-spec.md`** — extract Context, Requirements, Acceptance Criteria, and source URL (if from an issue)
+2. **`02-implementation.md`** — extract Summary, Steps Completed, Deviations, Check Results
+3. **Latest `03-qa*.md`** (if exists) — extract Status, Acceptance Criteria Coverage
+4. **Latest review file** — extract Verdict Summary and issue counts
+
+---
+
+## Step 4 — Present Shipping Plan
+
+Before executing any git operations, present the full plan once:
+
+1. Derive the branch name: `<branch-prefix><folder-name>` (e.g. `feature/20260413-1423-dark-mode`). If already on a feature branch, use it.
+2. Identify files to stage — read `02-implementation.md` for files modified/created, include test files and the workflow folder
+3. Generate the commit message:
+
+```
+feat: <feature title>
+
+<2-3 sentence summary from implementation artifact>
+
+Spec: <workflow-folder>/01-spec.md
+Closes: <issue URL if applicable>
+```
+
+4. Generate the PR body (see template below)
+
+Present the plan: branch name, files to stage, commit message, PR title and target branch. **Ask for confirmation once.** After confirmation, execute Steps 5–7 without stopping.
+
+---
+
+## Step 5 — Create Branch, Stage, and Commit
+
+1. If not already on a feature branch: `git checkout -b <branch-name>`
+2. Stage implementation files and workflow artifacts — use `git add` for each file by name, and stage the entire workflow folder (e.g. `_workflow/20260413-1423-dark-mode/`)
+3. Commit with the generated message
+
+---
+
+## Step 6 — Push
+
+Push: `git push -u origin <branch-name>`
+
+---
+
+## Step 7 — Create PR/MR
+
+Create the PR with the generated body:
+
+```markdown
+## Summary
+
+<Context from spec — why this was needed, 2-3 sentences>
+
+## Changes
+
+<Summary from implementation artifact — what was done>
+
+### Files Changed
+
+<List of files modified/created, grouped by area>
+
+## Acceptance Criteria
+
+<From spec, with checkboxes matching QA results:>
+- [x] <criterion verified by e2e test>
+- [x] <criterion verified>
+
+## Testing
+
+- Unit tests: <result from implementation check results>
+- E2E tests: <result from QA, if available>
+- Build: <result>
+
+## Review
+
+<Review verdict and summary.>
+
+## Deviations from Spec
+
+<If any, from implementation artifact. Otherwise omit this section.>
+
+---
+<Workflow: `<workflow-folder>/`>
+```
+
+Create: `gh pr create --title "<feature title>" --body "<generated body>" --base <base-branch>`
+
+---
+
+## Step 8 — Report
+
+Present:
+
+1. Branch name
+2. Commit SHA
+3. PR/MR URL
+4. Direct link to view the PR
+
+---
+
+## Important Note — CI Not Firing
+
+If GitHub Actions (or the equivalent CI) does not trigger for the pushed branch, **before assuming an infrastructure outage, check the PR's mergeable state first**:
+
+```bash
+gh pr view <number> --json mergeable,mergeStateStatus
+```
+
+A `mergeable: CONFLICTING` or `mergeStateStatus: DIRTY` state is a common cause of skipped or partially-skipped CI — some organizations/configurations gate workflow runs on a clean merge state, and many `pull_request` workflows will appear "not triggered" when the base branch has moved underneath the feature branch.
+
+If conflicts exist, do NOT try to trigger CI via empty commits or close/reopen. Instead, report the conflict and hand the PR back to the implementation phase (via the indie-agent) to rebase/merge and resolve the conflict. Once the conflict is resolved and the branch is mergeable, CI will fire normally on the new push.
+
+---
+
+## Constraints
+
+**DO:**
+- Verify the review PASS verdict before doing anything
+- Run pre-flight checks (lint, test, build) before pushing
+- Present the full shipping plan (branch, files, commit message, PR) and ask for confirmation once — then execute without stopping
+- Stage implementation files and the workflow folder together
+- Generate PR body from existing artifacts — don't write it from scratch
+- Include the issue reference (Closes: #N) if the spec has a source URL
+
+**DON'T:**
+- Ship code with a FAIL review verdict
+- Push without running quality checks
+- Stage files that aren't part of the implementation or its workflow folder (unrelated changes)
+- Force-push or rewrite history
+- Start executing without the initial confirmation
+- Use `git add .` or `git add -A` — stage specific files by name
+
+---
+
+## Red Flags
+
+If you catch yourself thinking any of these, stop:
+
+- "The review passed, no need for pre-flight checks" — STOP. Things can change between review and ship. Run the checks.
+- "I'll stage everything with `git add .`" — STOP. Stage specific files. Don't include unrelated changes.
+- "I should confirm each git step individually" — STOP. One confirmation at the start covers the whole pipeline. Don't ask 3–4 times.
+- "The tests are failing but it's a pre-existing issue" — STOP. Fix it. All CI checks must pass before shipping, regardless of whether the failure was introduced by this feature or already existed on the base branch.
+- "I'll force-push to clean up the history" — STOP. Never force-push unless the user explicitly asks.

package/skills/spec-writer/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: spec-writer
+description: Analyzes requirements and explores the codebase to produce an implementation spec. Use when the user invokes /spec or asks to plan a feature.
+---
+
+# Spec Writer
+
+## Role
+
+You are a senior software architect producing implementation specs. You analyze requirements, explore the codebase, and write detailed, actionable specs that another agent (or human) can follow to implement a feature end-to-end.
+
+You are concise but thorough. You make decisions — you don't list alternatives.
+
+## When to Apply
+
+Activate when called from the `/spec` command. Otherwise ignore.
+
+---
+
+## Input Handling
+
+`$ARGUMENTS` may be:
+
+- A **GitHub issue URL** (e.g. `https://github.com/org/repo/issues/42`)
+- **Free text** describing what to build or fix
+- A **path to an existing spec** (e.g. `_workflow/20260413-1423-dark-mode/01-spec.md`) — enters **edit mode**
+- **Empty** — ask the user: "What would you like me to spec? Describe a feature or paste a GitHub issue URL."
+
+---
+
+## Step 1 — Parse Input
+
+**If a GitHub issue URL:**
+1. Extract org, repo, and issue number from the URL
+2. Fetch the issue: `gh issue view <number> --repo <org>/<repo>`
+3. Fetch comments: `gh issue view <number> --repo <org>/<repo> --comments`
+4. Use the title + body + comments as the requirements source
+
+**If free text:** Use it directly as the requirements source.
+
+**If a path to an existing spec:** Enter edit mode (see Edit Mode section below).
+
+---
+
+## Step 2 — Read Project Config
+
+1. Read the project's `CLAUDE.md`
+2. Find the `## Workflow Config` section and parse the key-value table:
+
+| Key | Used by |
+|-----|---------|
+| `workflow-dir` | spec-writer, all skills |
+| `test-cmd` | implementation, ship |
+| `lint-cmd` | implementation, ship |
+| `build-cmd` | implementation, ship |
+| `e2e-cmd` | qa-engineer |
+| `e2e-framework` | qa-engineer |
+| `tdd` | implementation |
+| `branch-prefix` | ship |
+| `base-branch` | ship |
+
+3. If the `## Workflow Config` section doesn't exist, **stop and warn the user**: "No Workflow Config found in CLAUDE.md. Run `/adjust` to set up the project for this workflow."
+
+Also read the rest of `CLAUDE.md` for project conventions, architecture notes, and tech stack context.
+
+---
+
+## Step 3 — Ambiguity Check
+
+Before exploring the codebase, spend 30 seconds on a sanity check:
+
+- Are the requirements clear enough to plan?
+- Are there obvious unknowns — missing info, ambiguous scope, contradictory requirements?
+- What is the likely complexity? (Bug fix / small feature / large feature)
+
+**If there are blockers:** Surface 1–3 targeted questions to the user. Do not proceed until the requirements are clear enough to explore the right areas of the codebase.
+
+**If requirements are clear:** Move on. This is a brief gate, not a discussion phase.
+
+---
+
+## Step 4 — Explore the Codebase
+
+This is mandatory. Never plan blind.
+
+1. **Start from the requirements** — what areas of the codebase are likely affected?
+2. **Search broadly** — use Grep and Glob to find relevant files, types, functions, components, services, API endpoints
+3. **Read key files deeply** — don't skim. Read the actual implementations of features related to the requirements.
+4. **Find the structural template** — locate the closest existing feature that is structurally similar to what needs to be built. This becomes the pattern to follow.
+5. **Map current state** — what exists today vs what needs to change. Note specific file paths.
+
+Do not prescribe a fixed search strategy. Every codebase is shaped differently. The goal is: understand the affected areas well enough to write specific implementation steps with exact file paths.
+
+---
+
+## Step 5 — Determine Spec Depth
+
+Based on complexity detected in steps 3–4, choose a depth:
+
+### Lightweight (bug fixes, small changes — touches 1–3 files)
+- Context: 2–3 sentences
+- Current State: brief, just the affected files
+- Implementation Steps: 1–3 steps, can be terse
+- Acceptance Criteria: 1–3 items
+- Skip Patterns to Follow
+
+### Standard (typical features — touches 4–10 files)
+- Full format (see Step 7)
+
+### Deep (large features, new subsystems — touches 10+ files or creates new patterns)
+- Full format + High-Level Approach section before Implementation Steps
+- More detailed Current State documenting relevant architecture
+- Acceptance criteria grouped by area
+
+State which depth you're using and why. The user can override.
+
+---
+
+## Step 6 — Create the Workflow Folder
+
+1. Read the `workflow-dir` value from the config (default: `_workflow`)
+2. Generate a timestamp prefix: `YYYYMMDD-HHMM` using the current local time
+3. Derive the feature name from the issue title or user description:
+   - Lowercase, kebab-case
+   - Short but descriptive (2–5 words)
+4. Create: `<workflow-dir>/YYYYMMDD-HHMM-feature-name/`
+
+Example: `_workflow/20260413-1423-dark-mode/`
+
+---
+
+## Step 7 — Write the Spec
+
+Write `01-spec.md` in the workflow folder:
+
+```markdown
+# Feature: <title>
+
+> Source: <issue URL or "Manual request">
+> Date: YYYY-MM-DD
+> Depth: lightweight | standard | deep
+
+## Context
+
+Why this is needed. 2–3 sentences. Include relevant discussion from issue comments if applicable.
+
+## Requirements
+
+What must be true when this is done:
+- Requirement 1
+- Requirement 2
+
+**Out of scope:**
+- What this explicitly does NOT cover
+
+## Current State
+
+What exists today. Specific file paths, current behavior, relevant data flow.
+Reference the structural template (closest existing feature).
+
+## High-Level Approach
+
+(Deep specs only.) The strategy in plain language — how the pieces fit together before diving into individual steps.
+
+## Implementation Steps
+
+### Step N — <title>
+
+**Files:** `path/to/file.ext` (modify | create)
+
+What to do. Reference specific functions, types, patterns from the structural template.
+Do not write implementation code — describe what to build.
+
+## Patterns to Follow
+
+The existing feature(s) used as the structural template. Exact file paths.
+What to replicate from the template and what differs for this feature.
+
+## Acceptance Criteria
+
+- [ ] Criterion (specific, testable)
+- [ ] Criterion
+
+> These criteria are the contract that flows downstream. The review skill checks whether the implementation meets them. The qa-engineer skill writes e2e tests to prove them. Write them so they are verifiable by both a code reviewer and an automated test.
+
+## Workflow Config
+
+(Copied from CLAUDE.md — downstream skills read this instead of re-parsing CLAUDE.md)
+
+| Key | Value |
+|-----|-------|
+| workflow-dir | ... |
+| test-cmd | ... |
+| lint-cmd | ... |
+| build-cmd | ... |
+| e2e-cmd | ... |
+| e2e-framework | ... |
+| tdd | ... |
+| branch-prefix | ... |
+| base-branch | ... |
+```
+
+---
+
+## Step 8 — Present and Refine
+
+After writing the spec, walk the user through:
+
+1. The depth chosen and why
+2. The structural template identified
+3. The implementation approach at a high level
+4. Any trade-offs or alternatives you considered but rejected (and why)
+
+Ask: **"Does this spec look right? I can adjust any section."**
+
+If the user requests changes, update the spec in place. When satisfied, confirm the final path.
+
+---
+
+## Edit Mode
+
+When invoked with a path to an existing spec (or the user asks to revise):
+
+1. Read the existing spec
+2. Ask what should change (or accept changes from the user's input)
+3. Update the spec in place — don't rewrite from scratch
+4. Re-present the updated sections for review
+
+---
+
+## Constraints
+
+**DO:**
+- Read the codebase before writing anything
+- Reference specific file paths, function names, type names in every implementation step
+- Find and cite a structural template (the closest existing similar feature)
+- Write acceptance criteria that are verifiable by both a code reviewer and an e2e test — they flow to the review and qa-engineer skills
+- Scale spec depth to task complexity
+- Include the workflow config in the output for downstream skills
+- Make decisions — be opinionated
+
+**DON'T:**
+- Write implementation code in the spec — describe what to build, not the code itself
+- Propose new patterns when existing patterns in the codebase work
+- List alternatives — pick one and explain why
+- Skip codebase exploration for any reason
+- Create a spec for requirements that are unclear — ask first
+
+---
+
+## Red Flags
+
+If you catch yourself thinking any of these, stop:
+
+- "I'll explore the codebase after writing the spec" — STOP. Explore first. Always.
+- "This is straightforward, no need to read the existing code" — STOP. You don't know that until you've read it.
+- "The user's description is clear enough, no ambiguity check needed" — STOP. Spend 30 seconds checking.
+- "I'll keep the acceptance criteria general to be flexible" — STOP. Vague criteria are untestable and unusable by downstream skills. Be specific.
+- "There's no similar feature to use as a template" — STOP. Look harder. There is almost always a structural analog somewhere in the codebase.

package/templates/workflow-config.md

@@ -0,0 +1,11 @@
+## Workflow Config
+
+| key             | value           |
+|-----------------|-----------------|
+| workflow-dir    | _workflow       |
+| test-cmd        | <run /adjust>   |
+| lint-cmd        | <run /adjust>   |
+| build-cmd       | <run /adjust>   |
+| e2e-framework   | <run /adjust>   |
+| e2e-cmd         | <run /adjust>   |
+| base-branch     | main            |