Initial commit
This commit is contained in:
Zhongwei Li
14
.claude-plugin/plugin.json
Normal file
14
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"name": "spec-manager-plugin",
|
||||
"description": "Proactive skill that automatically manages and updates application specifications when code changes occur.",
|
||||
"version": "1.1.0",
|
||||
"author": {
|
||||
"name": "Hiroshi Ayukawa"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
],
|
||||
"commands": [
|
||||
"./commands"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# spec-manager-plugin
|
||||
|
||||
Proactive skill that automatically manages and updates application specifications when code changes occur.
|
||||
3
commands/update-spec.md
Normal file
3
commands/update-spec.md
Normal file
@@ -0,0 +1,3 @@
|
||||
Update Specification Documents using spec-manager skill and write to files PRD.md, AppFlow.md, TechStack.md, FileStructure.md, FrontendGuidelines.md, BackendStructure.md, DevInstructions.md in the .spec-manager directory.
|
||||
|
||||
$ARGUMENTS
|
||||
53
plugin.lock.json
Normal file
53
plugin.lock.json
Normal file
@@ -0,0 +1,53 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:hiroshi75/ccplugins:spec-manager-plugin",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "10b0bdd6b72840013f00ccf1863c511eca3ed462",
|
||||
"treeHash": "34d0d7cba13ad862afec30b7b5ae6fe8cbeb7e319491b6eff23d5160c763d589",
|
||||
"generatedAt": "2025-11-28T10:17:29.023955Z",
|
||||
"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": "spec-manager-plugin",
|
||||
"description": "Proactive skill that automatically manages and updates application specifications when code changes occur.",
|
||||
"version": "1.1.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "555fe264be62832711ea7dad0c367210e5b17bb2d1da4eff64cb979c6024a43d"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "bcb2b71013781fe06eb90dcba661ca42e07ed25a3e34ebb67ae01be9a8471e09"
|
||||
},
|
||||
{
|
||||
"path": "commands/update-spec.md",
|
||||
"sha256": "8bdc311f48f4d8aa1cf79f6e3a990af80a7c8ebeb0cee3cf9b5bd166e5640512"
|
||||
},
|
||||
{
|
||||
"path": "skills/spec-manager/README.md",
|
||||
"sha256": "e31c30cb9c520c1fc8167390c807fffab25ec632e82eb0e237f4c25be32f979a"
|
||||
},
|
||||
{
|
||||
"path": "skills/spec-manager/SKILL.md",
|
||||
"sha256": "d58558c46d92758941e5ca5ee6fa5079a753f5e141a292718e334273f12575b5"
|
||||
}
|
||||
],
|
||||
"dirSha256": "34d0d7cba13ad862afec30b7b5ae6fe8cbeb7e319491b6eff23d5160c763d589"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
75
skills/spec-manager/README.md
Normal file
75
skills/spec-manager/README.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# spec-manager
|
||||
|
||||
**PROACTIVE SKILL** - Automatically manage and update application specification documents. Claude invokes this skill automatically when code changes occur or specifications need updating, keeping your documentation synchronized with your codebase.
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
/plugin marketplace add hiroshi75/ccplugins
|
||||
/plugin install spec-manager-plugin@hiroshi75
|
||||
```
|
||||
|
||||
## Automatic Triggers
|
||||
|
||||
Claude **automatically invokes** this skill when:
|
||||
|
||||
- **Starting features** - Before implementing new functionality
|
||||
- **Completing changes** - After modifying 3+ files or major features
|
||||
- **Refactoring** - When architecture or project structure changes
|
||||
- **Keywords detected** - When user mentions: 仕様, spec, design, architecture, requirements, PRD
|
||||
- **Session end** - After development sessions with substantial changes
|
||||
|
||||
**No manual action required** - Claude keeps specifications synchronized automatically.
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
Detect changes → Auto-invoke skill → Update .spec-manager/ docs → Notify user
|
||||
```
|
||||
|
||||
## Manual Invocation (Optional)
|
||||
|
||||
To manually trigger specification updates:
|
||||
|
||||
```
|
||||
/spec-manager-plugin:update-spec
|
||||
```
|
||||
|
||||
With language preference:
|
||||
|
||||
```
|
||||
/spec-manager-plugin:update-spec 日本語で
|
||||
```
|
||||
|
||||
## Specification Documents
|
||||
|
||||
The following documents are maintained in `.spec-manager/`:
|
||||
|
||||
| Document | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| **PRD.md** | Yes | Product Requirements Document |
|
||||
| **AppFlow.md** | Yes | Application flow and screen transitions |
|
||||
| **TechStack.md** | Yes | Technologies and dependencies used |
|
||||
| **FileStructure.md** | No | Project directory structure |
|
||||
| **FrontendGuidelines.md** | No | Frontend design principles |
|
||||
| **BackendStructure.md** | No | Backend architecture and DB/Storage |
|
||||
| **DevInstructions.md** | No | Development conventions and rules |
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Change Detection** - Claude monitors development activities
|
||||
2. **Trigger Evaluation** - Checks if auto-invoke conditions are met
|
||||
3. **Skill Invocation** - Automatically invokes spec-manager skill
|
||||
4. **Document Update** - Updates relevant specification documents
|
||||
5. **User Notification** - Reports what was updated with summary
|
||||
|
||||
## Example Notification
|
||||
|
||||
After automatic invocation, you'll see:
|
||||
|
||||
```
|
||||
Specification documents have been automatically updated:
|
||||
- PRD.md: Added authentication feature requirements
|
||||
- TechStack.md: Updated with JWT library dependencies
|
||||
- FileStructure.md: Reflected new auth/ directory structure
|
||||
```
|
||||
340
skills/spec-manager/SKILL.md
Normal file
340
skills/spec-manager/SKILL.md
Normal file
@@ -0,0 +1,340 @@
|
||||
---
|
||||
name: spec-manager
|
||||
description: |
|
||||
MANDATORY specification writing skill. ONLY way to create/update specs.
|
||||
|
||||
Auto-invoke when:
|
||||
- Creating specs: New projects, features ("I want to create XX")
|
||||
- Updating specs: Feature additions, requirement changes, architecture updates
|
||||
- Syncing specs: Major code changes (3+ files), refactoring, session end
|
||||
- Keywords: specifications/spec/design/architecture/requirements/PRD
|
||||
|
||||
Outputs to .spec-manager/. Critical rules and workflow details in skill body.
|
||||
---
|
||||
|
||||
# spec-manager Skill
|
||||
|
||||
This skill writes and displays the application's specification documents. It is used before implementation, before adding new features, or when design changes are made, to update the documents and notify users.
|
||||
|
||||
## 🚨 Critical Rules
|
||||
|
||||
**NEVER write spec/design/architecture documents to ANY location except `.spec-manager/`**
|
||||
|
||||
- NEVER create `docs/`, `specifications/`, `design/` directories for spec content before `.spec-manager/` exists
|
||||
- NEVER write PRD.md, TechStack.md, design docs, architecture docs to any location except `.spec-manager/`
|
||||
- ALWAYS invoke this skill FIRST for ANY specification-related documentation
|
||||
- Other documentation (README, API reference, user guides) allowed ONLY AFTER `.spec-manager/` is complete
|
||||
|
||||
**Auto-invoke triggers (expanded):**
|
||||
|
||||
- Writing spec/design/architecture/requirements documents (any directory, any filename)
|
||||
- Creating PRD, tech spec, design doc, architecture doc (any location)
|
||||
- User creation requests ("I want to create XX" with/without URL)
|
||||
- Starting implementation of new features
|
||||
- Completing significant changes (3+ files modified)
|
||||
- Major refactoring or architectural changes
|
||||
- Keywords: specifications/spec/specification/design/architecture/requirements/PRD/document
|
||||
- Session end with specification changes
|
||||
|
||||
## Standard Workflow
|
||||
|
||||
**0. FIRST:** Verify `.spec-manager/` exists and is current. If not, run this skill before any other documentation.
|
||||
|
||||
**1. Delegate to specialized skills (if available):**
|
||||
|
||||
- Check if specialized planning skills exist
|
||||
- Record TODO to return to spec-manager after planning
|
||||
- Delegate planning to specialized skill
|
||||
- Return here to write specification documents
|
||||
|
||||
**2. Interactive clarification (if requirements unclear):**
|
||||
|
||||
- Use `AskUserQuestion` tool with numbered options
|
||||
- Ask one question at a time
|
||||
- Build specifications incrementally
|
||||
|
||||
**3. Write/update specifications:**
|
||||
|
||||
- Write to `.spec-manager/` directory ONLY via this skill
|
||||
- Notify user of updates
|
||||
|
||||
**4. AFTER step 3:** Other documentation (README, etc.) can be created if needed
|
||||
|
||||
**Question format:** Always provide numbered options (1, 2, 3..., 1-1, 1-2,...) when asking specification questions.
|
||||
|
||||
## Dual Purpose: Specification Writing AND Requirements Clarification
|
||||
|
||||
This skill serves two primary functions:
|
||||
|
||||
### 1. Delegating to Specialized Planning Skills (Priority)
|
||||
|
||||
**When to delegate**: If other specialized skills for planning specifications are available in the system (e.g., `langgraph-master`, `business-panel`, domain-specific planning skills), delegate the planning process to them first.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. Detect that specifications need to be created or updated
|
||||
2. Check if specialized planning skills are available
|
||||
3. If available:
|
||||
- **Record a TODO** using `TodoWrite` to return to `spec-manager` skill after planning completes
|
||||
- Example TODO: "Return to spec-manager to write specification documents after planning"
|
||||
- Invoke the appropriate specialized skill for planning
|
||||
4. Wait for planning completion (the TODO ensures we don't forget to return)
|
||||
5. Return to this skill to write the specification documents based on the planning output
|
||||
6. Mark the TODO as completed
|
||||
7. Update `.spec-manager/` directory with the specifications
|
||||
|
||||
**Example**: If planning a LangGraph application, delegate to `langgraph-master` skill for architectural planning, then return here to write the formal specification documents.
|
||||
|
||||
### 2. Interactive Requirements Clarification (When No Specialized Skills)
|
||||
|
||||
**When to use**: If no specialized planning skills are available, OR if the user's requirements are unclear or ambiguous even after initial analysis.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. Detect that specifications are unclear or incomplete
|
||||
2. Automatically invoke this skill's interactive questioning mode
|
||||
3. Use `AskUserQuestion` tool to ask **one question at a time**
|
||||
4. Provide **clear options** for users to select from (when possible)
|
||||
5. Build specifications incrementally based on user's answers
|
||||
6. After gathering sufficient information, synthesize and confirm with user
|
||||
7. Write the specification documents to `.spec-manager/` directory
|
||||
|
||||
**Example**: User says "I want to create a web app" without details → This skill automatically starts asking:
|
||||
|
||||
- "What type of web application?" [E-commerce, Blog, Dashboard, Social network]
|
||||
- "Who are the target users?" [General public, Business users, Internal team]
|
||||
- Continue with technical stack, features, architecture, etc.
|
||||
|
||||
See the **"Clarifying Unclear Specifications"** section below for detailed questioning methodology.
|
||||
|
||||
## Proactive Usage Guidelines
|
||||
|
||||
**IMPORTANT**: This skill should be invoked **automatically and proactively** by Claude without waiting for explicit user requests.
|
||||
|
||||
### How to Invoke Proactively
|
||||
|
||||
When conditions are met, Claude should:
|
||||
|
||||
1. **Detect the trigger condition** (e.g., completed 5 file changes for new auth feature)
|
||||
2. **Automatically invoke this skill** without asking for permission first
|
||||
3. **Update specification documents** in `.spec-manager/` directory
|
||||
4. **Notify the user** with a summary like:
|
||||
```
|
||||
📝 Specification documents have been automatically updated:
|
||||
- PRD.md: Added authentication feature requirements
|
||||
- TechStack.md: Updated with JWT library dependencies
|
||||
- FileStructure.md: Reflected new auth/ directory structure
|
||||
```
|
||||
|
||||
### What NOT to Do
|
||||
|
||||
❌ **Don't wait** for explicit `/update-spec` command after every change
|
||||
❌ **Don't ask** "Should I update the specifications?" - just do it proactively
|
||||
❌ **Don't ignore** completed implementations - always sync specifications
|
||||
❌ **Don't skip** specification updates when user is focused on coding
|
||||
|
||||
### Integration with Development Workflow
|
||||
|
||||
```
|
||||
Development Flow:
|
||||
1. User requests feature → Invoke spec-manager (initialize/review specs)
|
||||
2. Implement feature → Track changes
|
||||
3. Complete implementation → Invoke spec-manager (auto-update specs)
|
||||
4. Mark task complete → Specifications already synchronized ✅
|
||||
```
|
||||
|
||||
### Clarifying Unclear Specifications
|
||||
|
||||
When the user's requirements or specifications are unclear or incomplete, use an **interactive questioning approach** to systematically gather information:
|
||||
|
||||
#### Process for Specification Clarification
|
||||
|
||||
1. **Identify Gaps**: Determine what information is missing or ambiguous
|
||||
|
||||
- Product requirements unclear?
|
||||
- Technical stack not specified?
|
||||
- User flows undefined?
|
||||
- Architecture decisions needed?
|
||||
|
||||
2. **Ask One Question at a Time**: Use the `AskUserQuestion` tool to gather information progressively
|
||||
|
||||
- **DO NOT** ask multiple complex questions simultaneously
|
||||
- Focus on one aspect at a time for clarity
|
||||
- Provide concrete options when possible
|
||||
|
||||
3. **Provide Clear Options**: Give users specific choices to select from
|
||||
|
||||
- Example options for architecture: "Monolith", "Microservices", "Serverless"
|
||||
- Example options for database: "PostgreSQL", "MongoDB", "SQLite"
|
||||
- Always include descriptions explaining each option's trade-offs
|
||||
|
||||
4. **Build Incrementally**: Use each answer to inform the next question
|
||||
|
||||
- Start with high-level decisions (purpose, target users, core features)
|
||||
- Move to technical choices (stack, architecture, database)
|
||||
- Finally address implementation details (deployment, testing, monitoring)
|
||||
|
||||
5. **Synthesize and Confirm**: After gathering information, summarize and confirm
|
||||
- Present the collected requirements back to the user
|
||||
- Ask for confirmation before writing specification documents
|
||||
- Allow the user to correct or refine any points
|
||||
|
||||
#### Example Question Flow
|
||||
|
||||
```
|
||||
Question 1: "What is the primary purpose of this application?"
|
||||
Options: ["E-commerce platform", "Content management system", "Data analytics dashboard", "Social network"]
|
||||
|
||||
↓ User selects "E-commerce platform"
|
||||
|
||||
Question 2: "Who are the target users?"
|
||||
Options: ["B2C consumers", "B2B businesses", "Internal company use", "Multi-tenant SaaS"]
|
||||
|
||||
↓ User selects "B2C consumers"
|
||||
|
||||
Question 3: "What are the core features needed for launch?"
|
||||
Options: [Allow multiple selections: "Product catalog", "Shopping cart", "Payment processing", "User accounts", "Order tracking"]
|
||||
|
||||
↓ Continue building specification incrementally
|
||||
```
|
||||
|
||||
#### Best Practices for Questions
|
||||
|
||||
- **Be Specific**: Ask about concrete decisions, not abstract concepts
|
||||
- **Offer Context**: Explain why you're asking and how it affects the design
|
||||
- **Limit Options**: Provide 2-4 options per question for manageability
|
||||
- **Allow "Other"**: The `AskUserQuestion` tool automatically provides an "Other" option
|
||||
- **Track Progress**: Keep track of what has been clarified and what remains unclear
|
||||
- **Document Decisions**: Record the user's answers in the appropriate specification files
|
||||
|
||||
#### When to Use This Approach
|
||||
|
||||
- ✅ User says "I want to create XX" without detailed requirements
|
||||
- ✅ Reference URLs are vague or incomplete
|
||||
- ✅ Project is in early conceptual stage
|
||||
- ✅ User is unsure about technical decisions
|
||||
- ✅ Multiple valid approaches exist and user preference is needed
|
||||
|
||||
## Working with Reference URLs
|
||||
|
||||
When users provide URLs as references for specification writing, follow these comprehensive analysis guidelines:
|
||||
|
||||
### For Documentation Sites
|
||||
|
||||
When the URL points to official documentation, tutorials, or technical guides:
|
||||
|
||||
1. **Read the Main Page Thoroughly**
|
||||
|
||||
- Extract key concepts, features, and requirements
|
||||
- Identify the overall structure and purpose
|
||||
|
||||
2. **Explore Subsections and Subpages**
|
||||
|
||||
- Navigate through all relevant subsections linked from the main page
|
||||
- Check navigation menus, sidebars, and "Related Pages" sections
|
||||
- Read "Getting Started", "Architecture", "Best Practices" sections if available
|
||||
- Don't miss important details in nested pages
|
||||
|
||||
3. **Synthesize Information**
|
||||
- Integrate information from all subsections into a coherent specification
|
||||
- Ensure consistency across different parts of the documentation
|
||||
- Capture both high-level concepts and implementation details
|
||||
|
||||
### For AI Conversation Pages (ChatGPT, Claude, etc.)
|
||||
|
||||
When the URL points to an AI conversation or chat transcript:
|
||||
|
||||
1. **Read the Entire Conversation**
|
||||
|
||||
- Start from the beginning, not just the latest messages
|
||||
- Understand the context and evolution of ideas
|
||||
- Track how requirements or designs changed throughout the discussion
|
||||
|
||||
2. **Identify the Final Conclusion**
|
||||
|
||||
- Look for the most recent, refined version of requirements or designs
|
||||
- Earlier ideas may have been revised or rejected - focus on what was ultimately decided
|
||||
- Pay attention to phrases like "final version", "let's go with", "decided to", "conclusion"
|
||||
|
||||
3. **Extract Actionable Specifications**
|
||||
|
||||
- Base your specification documents on the **final conclusions**, not intermediate ideas
|
||||
- If conflicting information exists, prioritize the most recent decisions
|
||||
- Include reasoning behind key decisions if mentioned in the conversation
|
||||
|
||||
4. **Respect the Context**
|
||||
- Understand why certain decisions were made during the conversation
|
||||
- Capture important constraints or requirements that influenced the final design
|
||||
- Note any explicit user preferences or requirements stated in the conversation
|
||||
|
||||
### General Best Practices
|
||||
|
||||
- **Use WebFetch Tool**: Always use the WebFetch tool to access and analyze URLs
|
||||
- **Be Thorough**: Don't rush - comprehensive analysis leads to better specifications
|
||||
- **Ask for Clarification**: If the reference material is ambiguous or contradictory, ask the user
|
||||
- **Document Sources**: Note which parts of the specification came from the reference URLs
|
||||
|
||||
## Specification Content Guidelines
|
||||
|
||||
### Minimize Source Code in Specifications
|
||||
|
||||
**IMPORTANT**: Specification documents should focus on design, architecture, and requirements - NOT implementation details.
|
||||
|
||||
#### What to Include (✅)
|
||||
|
||||
- **Interfaces and Type Definitions**: Only the public API contracts
|
||||
|
||||
```typescript
|
||||
interface UserService {
|
||||
authenticate(credentials: Credentials): Promise<AuthResult>;
|
||||
getUserProfile(userId: string): Promise<UserProfile>;
|
||||
}
|
||||
```
|
||||
|
||||
- **Data Types and Schemas**: Essential data structure definitions
|
||||
|
||||
```typescript
|
||||
type User = {
|
||||
id: string;
|
||||
name: string;
|
||||
email: string;
|
||||
role: "admin" | "user";
|
||||
};
|
||||
```
|
||||
|
||||
- **API Contracts**: Endpoint definitions, request/response formats
|
||||
- **Configuration Schemas**: Environment variables, config file structures
|
||||
|
||||
#### What to Avoid (❌)
|
||||
|
||||
- **Implementation Code**: Full function bodies, business logic, algorithms
|
||||
- **Helper Functions**: Utility functions and internal implementation details
|
||||
- **Repetitive Code Examples**: Multiple similar examples of the same pattern
|
||||
- **Long Code Blocks**: Any code snippet longer than 10-15 lines
|
||||
|
||||
#### Best Practices
|
||||
|
||||
- **Focus on "What" not "How"**: Describe what the system does, not how it's implemented
|
||||
- **Use Diagrams Over Code**: Prefer flowcharts, architecture diagrams, and sequence diagrams
|
||||
- **Reference Files Instead**: Point to actual source files rather than duplicating code
|
||||
- Example: "See `src/auth/UserService.ts` for implementation details"
|
||||
- **Keep Examples Minimal**: If code examples are necessary, show only the essential structure
|
||||
|
||||
## Location for Saving Specifications and order for writing
|
||||
|
||||
Specification documents are saved in the `.spec-manager` directory at the project root.
|
||||
|
||||
The following documents are stored (Do not change the following file names):
|
||||
|
||||
1. .spec-manager/PRD.md: _Required_ Product Requirements Document
|
||||
2. .spec-manager/TechStack.md: _Required_ Description of the technologies used
|
||||
3. Write these in parallel:
|
||||
- .spec-manager/AppFlow.md: _Required_ Application screen transition and flow diagrams
|
||||
- .spec-manager/FileStructure.md: Directory structure (excluding `.claude`, `node_modules`, etc.)
|
||||
- .spec-manager/BackendStructure.md: (If applicable) Design principles and guidelines for the backend, such as DB and Storage structures
|
||||
- .spec-manager/FrontendGuidelines.md: (If applicable) Design principles and guidelines for the frontend
|
||||
- .spec-manager/DevInstructions.md: Rules file. A natural language document describing the conventions and development rules that should be followed by the AI agents in this project.
|
||||
|
||||
You can write other specification documents as needed, but **the documents listed above are mandatory**.
|
||||
|
||||
So if those files do not exist, please create them first.
|
||||
Reference in New Issue
Block a user