Initial commit

2025-11-30 08:39:37 +08:00
commit 8b2a41253c
6 changed files with 354 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "speckl",
+  "description": "SPECKL workflow commands for specification-driven development with human-AI collaboration. Create minimal specs (specks), break them into tasks, and maintain clear boundaries for AI assistance.",
+  "version": "0.0.0-2025.11.28",
+  "author": {
+    "name": "Matt Brailsford & Phil Whittaker",
+    "email": "contact@speckl.dev"
+  },
+  "commands": [
+    "./commands"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# speckl
+
+SPECKL workflow commands for specification-driven development with human-AI collaboration. Create minimal specs (specks), break them into tasks, and maintain clear boundaries for AI assistance.
--- a/commands/spkl/init.md
+++ b/commands/spkl/init.md
@@ -0,0 +1,69 @@
+---
+allowed-tools: Bash(mkdir:*), Bash(echo:*), Bash(test:*), Bash(ls:*), Write
+description: Initialize a new specification
+argument-hint: <feature-description>
+---
+
+## Current Spec Status
+
+!`ls -d spec/[0-9][0-9][0-9]-* 2>/dev/null | wc -l | xargs -I {} echo "Total specs: {}"`
+
+## Your Task
+
+Initialize a new specification directory for feature: $ARGUMENTS
+
+**Steps:**
+
+1. **Check for CLAUDE.md**
+   - Test if `CLAUDE.md` exists in project root
+   - If missing, display warning:
+     ```
+     ⚠️  No CLAUDE.md found. SPECKL works best when your project has a CLAUDE.md file with:
+        - Project overview and tech stack
+        - Explicit non-goals (what you're NOT building)
+        - Key constraints (performance, compliance, tech limits)
+        - Design values (guiding principles)
+
+     This helps `/spkl:spec` create better, more contextual specifications.
+     ```
+
+2. **Extract and validate short name**
+   - Analyze the feature description in `$ARGUMENTS`
+   - Extract a concise, descriptive folder name (2-4 words max)
+   - Convert to kebab-case (lowercase, hyphens between words)
+   - Use only alphanumeric characters and hyphens
+   - Confirm the extracted name captures the essence of the feature
+
+3. **Create spec/ directory if it doesn't exist**
+
+4. **Determine next sequential ID**
+   - Parse existing `spec/[0-9][0-9][0-9]-*` directories
+   - Calculate next number (001, 002, ..., 010, 011, etc.)
+
+5. **Create specification directory**
+   - Format: `spec/[ID]-<extracted-name>/`
+   - Verify creation succeeded
+
+6. **Create README.md with description**
+   - Write `spec/[ID]-<extracted-name>/README.md`
+   - Format the original user description as markdown
+   - Use clear heading structure:
+     ```markdown
+     # <feature title>
+
+     ## Description
+
+     [Original user description]
+     ```
+
+7. **Update tracking file**
+   - Write `[ID]-<extracted-name>` to `spec/.current`
+   - This becomes the active spec for `/spkl:spec` and `/spkl:tasks`
+
+8. **Provide clear feedback**
+   - Show extracted folder name
+   - Show created directory path
+   - Confirm README.md contains the full description
+   - Explain next step: run `/spkl:spec` to create spec.md
+
+Use Bash and Write tools as needed. Handle errors gracefully.
--- a/commands/spkl/spec.md
+++ b/commands/spkl/spec.md
@@ -0,0 +1,133 @@
+---
+allowed-tools: Bash(cat:*), Bash(ls:*), Bash(test:*), Bash(touch:*), Bash(find:*), Bash(mkdir:*), Write. Web
+description: Create or review specification
+argument-hint: "feature description or refinement instructions"
+---
+
+## Context
+- Refinement instructions: $ARGUMENTS
+- Current spec: !`cat spec/.current 2>/dev/null || echo "No active spec"`
+- Project context: @CLAUDE.md
+
+## Your Task
+
+### Phase 0: Context Check
+
+1. **Check for CLAUDE.md**
+   - If `CLAUDE.md` is not found in project root, display this warning once:
+     ```
+     ⚠️  No CLAUDE.md found. SPECKL works best when your project has a CLAUDE.md file with:
+        - Project overview and tech stack
+        - Explicit non-goals (what you're NOT building)
+        - Key constraints (performance, compliance, tech limits)
+        - Design values (guiding principles)
+
+     Proceeding without project context may result in less focused specifications.
+     ```
+
+2. **Check for README.md**
+   - If `spec/<current-spec>/README.md` is not found, display this warning:
+     ```
+     ⚠️  No README.md found in the spec directory. This file should contain the feature description
+     to guide spec creation. Consider running `/spkl:init "feature description"` to set up properly.
+     ```
+
+### Phase 1: Read Feature Description
+
+1. **Read the README.md in the current spec directory**
+   - Read `spec/<current-spec>/README.md` to understand the feature description
+   - This is your primary source of truth for what the user wants to build
+
+### Phase 2: Research (REQUIRED)
+
+**Always research before proceeding:**
+1. Use the README.md description to understand the feature intent and context
+2. Search for similar existing implementations in the codebase
+3. Research relevant best practices, technical requirements, and security/performance considerations
+4. Validate assumptions about external APIs, libraries, or standards
+
+For refinements, focus on how `$ARGUMENTS` impacts the existing spec. Present findings before Phase 3.
+
+**Note**: The README.md acts as your research brief. Use it to guide what areas of the codebase need investigation.
+
+### Phase 3: Spec Creation or Review
+
+1. If `spec/<current-spec>/spec.md` **does not exist**, create it via Write with this minimal template (use README.md description and research findings to populate):
+
+    ```
+    # <short title>
+
+    # Goal
+    <user/system outcome>
+
+    # Inputs
+    - <specific data, params, triggers - include concrete values/enums if relevant>
+
+    # Outputs
+    - <UI state / API / file>
+
+    # Constraints
+    - <stack, performance, compliance>
+
+    # Requirements
+    - <WHAT needs to be built, not HOW - avoid code snippets, focus on components/capabilities>
+
+    # Dependencies
+    - <existing systems to study before implementing - read these to understand patterns and context>
+
+    # Out of Scope
+    - <explicit non-goals>
+
+    # Done
+    - <user-observable outcomes - behaviors the user can see/test, not technical tasks>
+    ```
+
+2. If `spec/<current-spec>/spec.md` **exists**:
+
+   * **Print the current spec content for reference.**
+   * If `$ARGUMENTS` is provided, apply the refinement instructions to improve the spec.
+   * If `$ARGUMENTS` is empty, offer to review the spec for clarity and completeness.
+   * Suggest improvements as a **unified diff** (GNU diff -u format) against the existing text.
+   * Interpret `$ARGUMENTS` as guidance on what to clarify, tighten, or adjust (e.g., "make constraints more specific", "clarify the auth flow", "add performance requirements").
+   * **Do not expand scope** unless explicitly requested—focus on ambiguity removal, tighter constraints, clearer Done items.
+
+## Critical Constraints
+
+**Evidence-Based Suggestions Only:**
+
+✅ **INCLUDE if there's direct evidence:**
+- Systems that **already display/process this exact data type** (e.g., if transaction log shows refunds, mention it for refund reason feature)
+- Areas that **must change** because they currently handle the feature being modified
+- Components **explicitly named** in the user's outline or existing spec
+
+❌ **EXCLUDE if speculative:**
+- Systems that *could theoretically* use this data but don't currently (e.g., analytics that doesn't mention refunds)
+- "Nice to have" integrations that aren't already connected
+- Tangentially related features that *might* benefit
+
+**Evidence test**: Before suggesting any system/area, confirm:
+1. Does it **currently** handle this exact data/feature? OR
+2. Did the user **explicitly mention** it in their outline?
+
+If both answers are "no", don't include it.
+
+## Guidelines
+
+* KISS. Boundaries over blueprints.
+* **Dependencies**: List existing systems developers should read/understand before starting. Include components you'll modify if understanding them is prerequisite.
+* **Requirements**: State WHAT needs building, not HOW. No code snippets. "Create RefundReason enum", not "public enum RefundReason { ... }"
+* **Done**: Observable user outcomes only. "Merchants can select refund reason" not "RefundReason enum created"
+* Prefer edits that **remove ambiguity** rather than add new scope.
+* Ground specs in research, not assumptions.
+* If uncertain about technical details, **search first, spec second**.
+* **When in doubt, leave it out.** Smaller, focused specs ship faster.
+* Better to under-specify than over-promise.
+* When refining, address the specific concerns in `$ARGUMENTS` while maintaining the spec's structure.
+
+## After Completion
+
+* For creation:
+  - Confirm the spec was written to `spec/<current-spec>/spec.md`
+  - Explain that the spec was created from the README.md description plus research findings
+  - Suggest running `/spkl:spec <refinements>` if changes are needed
+* For refinement: Ask if user wants to apply the suggested diff
--- a/commands/spkl/tasks.md
+++ b/commands/spkl/tasks.md
@@ -0,0 +1,84 @@
+---
+allowed-tools: Bash(cat:*), Bash(test:*), Write
+description: Create implementation task list
+---
+
+## Context
+
+- Current spec: !`cat spec/.current 2>/dev/null || echo "No active spec"`
+- Project context: @CLAUDE.md
+
+## Your Task
+
+### Phase 1: Validation
+
+1. Verify that `spec/<current-spec>/spec.md` exists
+2. If not found, inform the user to run `/spkl:spec` first
+
+### Phase 2: Task Breakdown
+
+Translate the spec into concrete, implementable tasks for human developers (not AI execution instructions):
+
+- **From Requirements section**: Create concrete implementation tasks
+- **From Dependencies section**: Understand context, but don't create "read X" tasks
+- **From Constraints section**: Use to inform task creation, but don't duplicate them as tasks
+- **From Done criteria**: Use to validate task completeness
+
+**Structure:**
+- Organize tasks into logical categories (e.g., "Core Models", "API Layer", "UI Components")
+- Number categories sequentially (1, 2, 3, etc.)
+- Number tasks within each category using decimal notation (1.1, 1.2, 1.3, etc.)
+- Use markdown checkbox notation for each task: `- [ ] 1.1 Task description`
+- Keep granularity appropriate (not too high-level, not overly detailed)
+- Focus on **what** needs to be done, not **how** to do it
+
+**Update behavior:**
+- If `spec/<current-spec>/tasks.md` exists, overwrite with fresh task list (developers manually check off completed tasks)
+
+- Save tasks to `spec/<current-spec>/tasks.md`
+
+## Critical Constraints
+
+- Do not include constraints, dependencies, or success criteria in the task list - those remain in the spec to guide implementation
+- Test scenarios/validation may be included as tasks if helpful, but consolidate into broad validation areas rather than individual test cases
+
+**Consolidation strategy for validation tasks:**
+- Group by **system area** (e.g., "API versioning", "UI validation", "persistence")
+- Group by **user flow** (e.g., "refund flows", "authentication flows")
+- Typically aim for 3-5 validation tasks total, not 7+
+- Example: Instead of separate tasks for "test full refund" and "test partial refund", use "Verify refund flows work correctly (full and partial)"
+
+## Guidelines
+
+- Tasks describe **what to build**, not implementation steps
+- Avoid creating meta-tasks like "Read file X" or "Understand Y" (Dependencies section already lists these)
+- Each task should be independently understandable and completable
+- Tasks should map clearly back to Requirements in the spec
+
+**Example format:**
+
+```markdown
+# <spec name>: Implementation Tasks
+
+**1. Core Models**
+- [ ] 1.1 Create RefundReason enum in transaction domain
+- [ ] 1.2 Add refund_reason field to Refund model
+
+**2. API Layer**
+- [ ] 2.1 Update RefundRequest schema to include reason
+- [ ] 2.2 Add validation for required reason field
+
+**3. UI Components**
+- [ ] 3.1 Add reason dropdown to refund form
+- [ ] 3.2 Update refund confirmation to display selected reason
+
+**4. Validation**
+- [ ] 4.1 Verify refund flows work correctly (full and partial refunds)
+- [ ] 4.2 Verify UI validation and display (dropdown, confirmation, history)
+- [ ] 4.3 Verify refund reason persistence in transaction logs
+```
+
+## After Completion
+
+- Confirm tasks were written to `spec/<current-spec>/tasks.md`
+- Summarize the number of categories and tasks created
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,53 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:mattbrailsford/speckl:",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "11f96f93464f20e704603ed518061f3215a02e5b",
+    "treeHash": "6f6ea2e7eeec7624dd1c336b72b3f0300bdb6bb449bb9e0e1edd969f5373aa31",
+    "generatedAt": "2025-11-28T10:27:02.929514Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "speckl",
+    "description": "SPECKL workflow commands for specification-driven development with human-AI collaboration. Create minimal specs (specks), break them into tasks, and maintain clear boundaries for AI assistance.",
+    "version": null
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "a6475d69eca56c18926d1a57677cc4a583d0fc5027c1bda888b7d49da68fd1f5"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "184a654da5acebc9c62331d03fc2073418fdf6899070cb1c6ea49c7096810386"
+      },
+      {
+        "path": "commands/spkl/init.md",
+        "sha256": "19ff2bb6042acf95e7df0c460df062bbeaed404135ae7281bc613d1cd6e118b6"
+      },
+      {
+        "path": "commands/spkl/tasks.md",
+        "sha256": "6780da9198d1abb61324ee0622edf4582412cbf6f6a24c356b218ecee12336f8"
+      },
+      {
+        "path": "commands/spkl/spec.md",
+        "sha256": "f6a0f8ddd3a0a40f5d7404a026694f31902a45aabaa691bc44a648dc1e659864"
+      }
+    ],
+    "dirSha256": "6f6ea2e7eeec7624dd1c336b72b3f0300bdb6bb449bb9e0e1edd969f5373aa31"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}