From 8b2a41253c7e8b4dfba60e49bc8cbe9f2f70d153 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:39:37 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 12 ++++ README.md | 3 + commands/spkl/init.md | 69 +++++++++++++++++++ commands/spkl/spec.md | 133 +++++++++++++++++++++++++++++++++++++ commands/spkl/tasks.md | 84 +++++++++++++++++++++++ plugin.lock.json | 53 +++++++++++++++ 6 files changed, 354 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/spkl/init.md create mode 100644 commands/spkl/spec.md create mode 100644 commands/spkl/tasks.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..08cf9e4 --- /dev/null +++ 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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..49bdb9a --- /dev/null +++ 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. diff --git a/commands/spkl/init.md b/commands/spkl/init.md new file mode 100644 index 0000000..d1b40aa --- /dev/null +++ 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: +--- + +## 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]-/` + - Verify creation succeeded + +6. **Create README.md with description** + - Write `spec/[ID]-/README.md` + - Format the original user description as markdown + - Use clear heading structure: + ```markdown + # + + ## Description + + [Original user description] + ``` + +7. **Update tracking file** + - Write `[ID]-` 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. \ No newline at end of file diff --git a/commands/spkl/spec.md b/commands/spkl/spec.md new file mode 100644 index 0000000..551ad29 --- /dev/null +++ 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//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//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//spec.md` **does not exist**, create it via Write with this minimal template (use README.md description and research findings to populate): + + ``` + # + + # Goal + + + # Inputs + - + + # Outputs + - + + # Constraints + - + + # Requirements + - + + # Dependencies + - + + # Out of Scope + - + + # Done + - + ``` + +2. If `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//spec.md` + - Explain that the spec was created from the README.md description plus research findings + - Suggest running `/spkl:spec ` if changes are needed +* For refinement: Ask if user wants to apply the suggested diff \ No newline at end of file diff --git a/commands/spkl/tasks.md b/commands/spkl/tasks.md new file mode 100644 index 0000000..9e7e42f --- /dev/null +++ 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//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//tasks.md` exists, overwrite with fresh task list (developers manually check off completed tasks) + +- Save tasks to `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 +# : 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//tasks.md` +- Summarize the number of categories and tasks created diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..3186b16 --- /dev/null +++ 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": [] + } +} \ No newline at end of file