@codename_inc/spectre 3.7.0 → 4.0.0

package/plugins/spectre-codex/skills/scope/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: "scope"
+description: "👻 | Interactively scope a feature or improvement, generating a complete Scope document that clarifies what's IN and OUT -- primary agent"
+user-invocable: true
+---
+
+# scope
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+# scope: Interactive Feature Scoping
+
+Collaborative workflow for structuring unstructured thoughts into clear scope boundaries through contextual brainstorming and targeted clarifications. Focuses on user value and scope boundaries before technical considerations. Output: comprehensive scope document with clear boundaries, user value, and key decisions saved to `{OUT_DIR}/concepts/scope.md`.
+
+## ARGUMENTS
+
+<ARGUMENTS> $ARGUMENTS </ARGUMENTS>
+
+## Step 1: Immediate Reply & Gather Context
+
+- **Action** — ImmediateReply: Respond before any tools.
+  - **If** `FROM_KICKOFF=true` → acknowledge kickoff context, read `KICKOFF_DOC`, extract (Core Problem, User Value, Decisions Made, Remaining Ambiguities, Key Code Refs), **SKIP to Step 3**
+  - **Else If** ARGUMENTS empty → probe for context enthusiastically
+  - **Else** → proceed to Step 2
+  - **CRITICAL**: No tool calls except reading kickoff doc when FROM_KICKOFF=true
+
+## Step 2: Interactive Scope Exploration
+
+**SKIP IF FROM_KICKOFF=true**
+
+- **Action** — ExploreScope: Collaborative dialogue focused on boundaries and user experience.
+
+  **CRITICAL**: Focus on WHAT, not HOW. Defer all technical/implementation questions until scope boundaries are finalized. Only ask technical questions if the scope itself is inherently technical (e.g., "migrate database from X to Y").
+
+  **PATTERN**: Lead with a rich initial exploration. In your FIRST response, propose concrete hypotheses AND ask 5-8 questions across multiple dimensions. Give the user a full landscape to react to, not a single thread to follow.
+
+  **FIRST RESPONSE FORMAT**:
+
+  > Here's my initial read on this, plus questions to help us explore the bounds:
+  >
+  > **My hypothesis**: [problem statement, who it affects, proposed IN/OUT]
+  >
+  > **Questions to explore**:
+  > 1. [User problem question]
+  > 2. [UX flow question]
+  > 3. [Boundary edge question]
+  > 4. [Alternative approach question]
+  > 5. [Success criteria question]
+  > 6. [Edge case question]
+  > ...
+  >
+  > Answer any/all that spark thoughts. Skip what's obvious.
+
+  **Question types to include** (aim for 5-8 total, mix from these):
+
+  - **User & Problem**: Who feels this most? What triggers the need? What's the cost of not solving it?
+  - **UX & Feel**: Should this feel fast or thorough? Guided or flexible? What's the ideal flow?
+  - **Boundaries**: What about [adjacent thing]—IN or OUT? If unlimited time, what else? What's essential for v1?
+  - **Alternatives**: I could see this as [A] or [B]. Which direction?
+  - **Edge cases**: What happens when [unusual situation]? Should we handle [error state]?
+  - **Success**: What makes you say "this shipped well"? What's the one thing we can't get wrong?
+
+  **DO NOT ask about**: implementation approach, technical trade-offs, architecture, or integration details until boundaries are confirmed.
+
+- **Action** — IterateBoundaries: After user responds, refine boundaries and ask targeted follow-ups on gaps.
+
+  > **Current Boundaries**: ✅ **IN**: \[list\] ❌ **OUT**: \[list\] ⚠️ **Unsure**: \[edge cases\]
+  >
+  > Any items to move? Add exclusions? Clarify edges? Reply 'looks good' to continue.
+
+- **Wait** — User confirms Scope boundaries are accurate
+
+## Step 3: Generate Targeted Clarifications
+
+- **Action** — DetermineOutputDir:
+
+  - **If** FROM_KICKOFF → use same dir as kickoff doc
+  - **Else** → `OUT_DIR = user_specified || docs/tasks/{branch_name}`
+  - `mkdir -p "$OUT_DIR"`
+
+- **Action** — GenerateTargetedQuestions: Create 3-6 questions based ONLY on remaining scope ambiguities from Step 2 (or kickoff's "Remaining Ambiguities").
+
+  **CRITICAL**: Only ask about unresolved scope ambiguities. Technical questions (architecture, trade-offs, integration) belong in `plan`, not here.
+
+- **Action** — SaveClarifications: Create `{OUT_DIR}/clarifications/scope_clarifications_{timestamp}.md`:
+
+  - Header: concept name, confirmed boundaries so far
+  - Questions: Each focused on a scope edge case with `<response></response>` block
+
+- **Action** — PromptUser: "Saved clarifications to `{path}`. Answer in `<response>` blocks. Reply 'Read it' when ready."
+
+- **Wait** — User replies
+
+- **Action** — ReadClarifications: Read file, use responses (proceed with assumptions if empty)
+
+## Step 4: Create Scope Document
+
+- **Action** — CreateScopeDoc: Generate `{OUT_DIR}/concepts/scope.md` (use scoped filename if exists).
+
+  **Priority**: User value and boundaries BEFORE technical details.
+
+  **Sections**: The Problem (pain, impact, current state) → Target Users (primary, secondary, needs) → Success Criteria (outcomes, metrics) → User Experience (journeys, principles, trade-offs) → Scope Boundaries (in/out/maybe/future) → Constraints (platform, perf, a11y, scale) → Integration (touches, avoids, dependencies) → Decisions (from clarifications + rationale) → Risks (UX, scope creep, open questions) → Next Steps (`plan` or `create_tasks`, complexity S/M/L)
+
+## Step 5: Light Technical Context (Optional)
+
+**Only if scope identifies specific technical/architecture integration points.**
+
+- **Action** — IdentifyTouchpoints: Identify desired areas of research, and dispatch parallel @analyst subagents to research each area. Surface-level only (component names, NOT implementation). List features this interacts with, constraints worth documenting, areas to avoid.
+
+- **Action** — UpdateScopeDoc: Add findings to Integration & Constraints sections if relevant.
+
+## Step 6: Final Review & Next Steps
+
+- **Action** — PresentDocForReview: Show final boundaries and next steps together.
+
+  > **Scope Complete**: `{OUT_DIR}/concepts/scope.md`
+  >
+  > **Final Boundaries**: ✅ **IN**: \[from doc\] ❌ **OUT**: \[from doc\] ⚠️ **Maybe/Future**: \[from doc\]
+  >
+  > Docs saved: `{OUT_DIR}/concepts/scope.md`, `{OUT_DIR}/clarifications/scope_clarifications_{timestamp}.md`
+  >
+  > Reply with any edits, updates, or clarifications — otherwise pick a next step:
+
+- **Action** — RenderFooter: Render Next Steps using `Skill(spectre-guide)` skill.
+
+  > **NOTE**: Do NOT wait for explicit approval. Present next steps immediately inline with the review. User can reply with scope edits OR jump straight into a next step command. If user replies with edits, apply them to the scope doc and re-present.

package/plugins/spectre-codex/skills/ship/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: "ship"
+description: "👻 | Autonomous end-to-end: brain dump -> scope -> TDD -> commit -> rebase -> PR"
+user-invocable: true
+---
+
+# ship
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+# ship: Autonomous End-to-End Delivery
+
+Take a brain dump and autonomously produce a reviewable PR. Zero confirmation gates — scope, implement with TDD, sweep, rebase, and open a PR.
+
+**Execution Style**: Fully autonomous. No user approval gates. Parse intent, build it, ship the PR.
+
+## ARGUMENTS
+
+<ARGUMENTS> $ARGUMENTS </ARGUMENTS>
+
+## Step (1/8) - Parse Context
+
+- **Action** — ParseBrainDump: Extract from ARGUMENTS:
+  - `INTENT_TYPE`: `feat` or `fix` (infer from context — new behavior = feat, broken behavior = fix)
+  - `TARGET_BRANCH`: Extract if specified (e.g., "rebase onto develop"), default `origin/main`
+  - `SCOPE_SUMMARY`: 1-2 sentence distillation of what to build/fix
+  - `RELEVANT_FILES`: Any files, components, or areas mentioned
+  - `CONTEXT`: Remaining context, constraints, preferences
+- **Action** — ValidateInput:
+  - **If** ARGUMENTS empty → ask user for brain dump, then proceed autonomously
+  - **Else** → proceed
+
+## Step (2/8) - Ensure Worktree
+
+- **Action** — DetectBranch: `git rev-parse --abbrev-ref HEAD`
+  - **If** already in a worktree or on a non-main branch (not `main`, not `master`) → use current context, proceed
+  - **If** on `main` or `master` → use `EnterWorktree` to create an isolated worktree
+- **Action** — SetBranchName: Capture current branch name as `BRANCH_NAME` for artifact paths
+
+## Step (3/8) - Quick Scope
+
+- **Action** — DispatchResearch: Spawn parallel lightweight agents:
+
+  - `@finder` — Locate files related to `RELEVANT_FILES` and `SCOPE_SUMMARY`
+  - `@analyst` — Understand the relevant code area, key interfaces, existing patterns
+
+- **Action** — WriteScopeDoc: Create `docs/tasks/{BRANCH_NAME}/concepts/scope.md`:
+
+  ```markdown
+  # Scope: {SCOPE_SUMMARY}
+  
+  ## Objective
+  {1-2 sentences from brain dump}
+  
+  ## Type
+  {feat or fix}
+  
+  ## In Scope
+  - {bullet list of what will be done}
+  
+  ## Out of Scope
+  - {what this explicitly won't touch}
+  
+  ## Target Branch
+  {TARGET_BRANCH}
+  
+  ## Key Files
+  {from research — relevant files and their roles}
+  ```
+
+  Keep it \~20 lines. This is a lightweight scope, not full `scope`.
+
+## Step (4/8) - Create Tasks
+
+- **Action** — CreateTasks: Use `TaskCreate` to create 3-8 tasks proportional to scope complexity.
+  - Each task gets: clear `subject` (imperative), `description` (what to do + acceptance criteria), `activeForm` (present continuous)
+  - Order tasks by dependency — foundational work first
+  - Tasks are ephemeral and operational — no file artifact needed
+
+## Step (5/8) - Execute with TDD
+
+- **Action** — ExecuteLoop: For each task sequentially:
+
+  1. `TaskUpdate` → `in_progress`
+  2. Load `Skill(spectre-tdd)` for TDD methodology
+  3. Execute: RED (write failing test) → GREEN (minimal implementation) → REFACTOR (clean up)
+  4. Commit with conventional format: `{INTENT_TYPE}({scope}): {description}`
+  5. `TaskUpdate` → `completed`
+
+  **Rules**:
+
+  - One commit per task minimum
+  - Conventional commit format always
+  - TDD methodology for implementation tasks (skip for config/doc-only tasks)
+  - If a task reveals new work, create additional tasks rather than scope-creeping the current one
+
+## Step (6/8) - Sweep
+
+Inline sweep — same checklist as `sweep`, no subagents:
+
+### 6.1 Diff Sanity Check
+
+- Review full diff for unintentional changes (whitespace-only edits, merge artifacts)
+- Verify no accidentally staged files outside the intended scope
+- Confirm no secrets, API keys, credentials, or sensitive data in diff
+
+### 6.2 Logging Audit
+
+- Remove temporary/debug logging (console.log, print, debug flags)
+- Preserve intentional logs: errors, critical warnings, key state transitions
+- Verify log levels are appropriate for production context
+
+### 6.3 Code Hygiene
+
+- Remove commented-out code (it's in git history if needed)
+- Resolve or document any TODO/FIXME/HACK introduced in this session
+- Remove hardcoded test values that should be config/env
+
+### 6.4 Opportunistic Dead Code Cleanup
+
+- Orphaned imports with no usage in the file
+- Unused variables or functions declared but never referenced
+- Debug artifacts (debugger statements, leftover TODO/FIXME from this work)
+
+### 6.5 Lint (Strict)
+
+- Run the project linter and **fix all violations** — no skipping, no eslint-disable
+- Address structural lint issues by refactoring, not suppressing
+
+### 6.6 Test
+
+- Run affected tests + full test suite
+- Fix any failures caused by the changes
+- Do NOT write new tests here — that was done in Step 5
+
+### 6.7 Commit Sweep Fixes
+
+- If sweep produced changes, commit: `chore({scope}): sweep cleanup`
+
+## Step (7/8) - Rebase
+
+- **Action** — FetchLatest: `git fetch origin`
+- **Action** — CreateSafetyRef: `git branch backup/ship-$(date +%Y%m%d-%H%M%S)`
+- **Action** — Rebase: `git rebase {TARGET_BRANCH}`
+  - **If** conflicts → resolve automatically, favoring target branch conventions
+  - Track resolution decisions for PR summary
+- **Action** — VerifyPostRebase:
+  - Run linter — fix violations
+  - Run full test suite — fix failures
+  - Confirm commit count and no unexpected changes
+
+## Step (8/8) - Create PR
+
+- **Action** — PushBranch: `git push -u origin {BRANCH_NAME}`
+
+- **Action** — CreatePR: `gh pr create` with:
+
+  **Title**: `{INTENT_TYPE}({scope}): {SCOPE_SUMMARY}` (under 70 chars)
+
+  **Body**:
+
+  ```markdown
+  ## Summary
+  {From scope doc — objective and what was done}
+  
+  ## Changes
+  {Bulleted list derived from completed tasks}
+  
+  ## Test Plan
+  {Bulleted checklist — what was tested, what to verify manually}
+  
+  Shipped autonomously via `ship`
+  ```
+
+- **Action** — OutputPRUrl: Display the PR URL as the final deliverable
+
+## Next Steps
+
+Use `Skill(spectre-guide)` skill to render the Next Steps footer.

package/plugins/spectre-codex/skills/sweep/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: "sweep"
+description: "👻 | Light pass cleanup - clean, lint, test, commit"
+user-invocable: true
+---
+
+# sweep
+
+## Input Handling
+
+Treat the current command arguments as this workflow's input. When invoked from a slash command, use the forwarded `$ARGUMENTS` value.
+
+
+## Pre-Commit Sweep
+
+You are preparing uncommitted or recently committed changes for check-in. Perform a systematic cleanup, then commit with descriptive conventional commits.
+
+**Execution Style**: Fast, formulaic checklist. No subagents, no user approval gates. Execute each step and move on.
+
+### 1. Diff Sanity Check
+
+- Review full diff for unintentional changes (whitespace-only edits, merge artifacts)
+- Verify no accidentally staged files outside the intended scope
+- Confirm no secrets, API keys, credentials, or sensitive data in diff
+
+### 2. Logging Audit
+
+- Remove temporary/debug logging (console.log, print, debug flags, etc.)
+- Preserve intentional logs: errors, critical warnings, key state transitions
+- Verify log levels are appropriate for production context
+
+### 3. Code Hygiene
+
+- Remove commented-out code (it's in git history if needed)
+- Resolve or document any TODO/FIXME/HACK introduced in this session
+- Remove hardcoded test values that should be config/env
+
+### 4. Opportunistic Dead Code Cleanup
+
+Quick scan of changed files only — remove anything obviously dead, no deep investigation:
+
+- Orphaned imports with no usage in the file
+- Unused variables or functions declared but never referenced
+- Commented-out code blocks
+- Debug artifacts (debugger statements, leftover TODO/FIXME from this work)
+
+Do not hunt for dead code beyond the changed files. This is opportunistic, not forensic.
+
+### 5. Lint (Strict)
+
+- Run the project linter and **fix all violations** — no skipping, no eslint-disable
+- Address structural lint issues (file size, complexity thresholds) by refactoring, not suppressing
+- Verify .gitignore coverage (no temp files, build artifacts, IDE configs)
+
+### 6. Test
+
+- Identify test files related to the changed files (co-located tests, imports, shared modules)
+- Run those tests and the broader test suite
+- Fix any failures caused by the changes
+- Do NOT write new tests in this step — this is a sweep, not a test authoring pass
+
+### 7. Commit
+
+Group changes into logical conventional commits. Commits are project history and critical context for LLMs and future developers — invest in making them descriptive.
+
+**Format**: `type(scope): description`
+
+**Types**: feat, fix, refactor, test, chore, docs, style, perf
+
+**Grouping** — separate commits by concern:
+- Feature/behavior additions → `feat`
+- Refactors/cleanup with no behavior change → `refactor`
+- Bug fixes → `fix`
+- Test additions/updates → `test`
+- Config/dependency changes → `chore`
+- Documentation → `docs`
+
+**Commit message quality**:
+- Subject line answers: what changed and why (not "fix stuff" or "update files")
+- Include scope to locate the change: `feat(auth): add token refresh on 401 response`
+- If the commit touches multiple concerns, it's too big — split it
+- Body (optional) adds context: motivation, trade-offs, what was considered and rejected
+
+**Anti-patterns**:
+- `fix: updates` — says nothing
+- `refactor: clean up` — clean up what? why?
+- One giant commit for unrelated changes
+
+### 8. Render Footer
+
+Use `Skill(spectre-guide)` skill for Next Steps footer.

package/plugins/{spectre/skills/spectre-tdd → spectre-codex/skills/tdd}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: spectre-tdd
+name: "tdd"
 description: "Load this skill when executing TDD (Test-Driven Development) methodology. Use when implementing features via strict RED-GREEN-REFACTOR cycles, or when a prompt instructs execution via TDD."
 ---