Consolidate 36 per-change specs into 4 feature-level specs and align workflow
Replace granular change-level specs (001–036) with living feature specs: - 001-combatant-management (CRUD, persistence, clear, confirm buttons) - 002-turn-tracking (rounds, turn order, advance/retreat, top bar) - 003-combatant-state (HP, AC, conditions, concentration, initiative) - 004-bestiary (search, stat blocks, source management, panel UX) Workflow changes: - Add /integrate-issue command (replaces /issue-to-spec) for routing issues to existing specs or handing off to /speckit.specify - Update /sync-issue to list specs instead of requiring feature branch - Update /write-issue to reference /integrate-issue - Add RPI skills (research, plan, implement) to .claude/skills/ - Create docs/agents/ for RPI artifacts (research reports, plans) - Remove update-agent-context.sh call from /speckit.plan - Update CLAUDE.md with proportional scope-based workflow table - Bump constitution to 3.0.0 (specs describe features, not changes) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Lukas
146
.claude/skills/rpi-research/SKILL.md
Normal file
146
.claude/skills/rpi-research/SKILL.md
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
name: rpi-research
|
||||
description: Conduct deep codebase research and produce a written report. Use when the user explicitly requests research like "start a research for", "deeply investigate", or "fully understand how X works". Do not use for quick questions or simple code lookups.
|
||||
---
|
||||
|
||||
# Research Codebase
|
||||
|
||||
You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings.
|
||||
|
||||
## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
|
||||
- DO NOT suggest improvements or changes unless the user explicitly asks for them
|
||||
- DO NOT perform root cause analysis unless the user explicitly asks for them
|
||||
- DO NOT propose future enhancements unless the user explicitly asks for them
|
||||
- DO NOT critique the implementation or identify problems
|
||||
- DO NOT recommend refactoring, optimization, or architectural changes
|
||||
- ONLY describe what exists, where it exists, how it works, and how components interact
|
||||
- You are creating a technical map/documentation of the existing system
|
||||
|
||||
## Initial Setup
|
||||
|
||||
If the user already provided a research question or topic alongside this command, proceed directly to step 1 below. Only if no query was given, respond with:
|
||||
```
|
||||
I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
|
||||
```
|
||||
Then wait for the user's research query.
|
||||
|
||||
## Steps to follow after receiving the research query:
|
||||
|
||||
1. **Read any directly mentioned files first:**
|
||||
- If the user mentions specific files or docs, read them FULLY first
|
||||
- **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
|
||||
- **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks
|
||||
- This ensures you have full context before decomposing the research
|
||||
|
||||
2. **Analyze and decompose the research question:**
|
||||
- Break down the user's query into composable research areas
|
||||
- Take time to think deeply about the underlying patterns, connections, and architectural implications the user might be seeking
|
||||
- Identify specific components, patterns, or concepts to investigate
|
||||
- If you have a todo list, use it to track progress
|
||||
- Consider which directories, files, or architectural patterns are relevant
|
||||
|
||||
3. **Spawn parallel sub-agents to identify relevant files and map the landscape:**
|
||||
- Create multiple Task agents to search for files and identify what's relevant
|
||||
- Each sub-agent should focus on locating files and reporting back paths and brief summaries — NOT on deeply analyzing code
|
||||
- The key is to use these agents for discovery:
|
||||
- Search for files related to each research area
|
||||
- Identify entry points, key types, and important functions
|
||||
- Report back file paths, line numbers, and short descriptions of what each file contains
|
||||
- Run multiple agents in parallel when they're searching for different things
|
||||
- Remind agents they are documenting, not evaluating or improving
|
||||
- **If the user explicitly asks for web research**, spawn additional agents with WebSearch/WebFetch tools and instruct them to return links with their findings
|
||||
|
||||
4. **Read the most relevant files yourself in the main context:**
|
||||
- After sub-agents report back, identify the most important files for answering the research question
|
||||
- **Read these files yourself using the Read tool** — you need them in your own context to write an accurate, detailed research document
|
||||
- Do NOT rely solely on sub-agent summaries for the core findings — sub-agent summaries may miss nuances, connections, or important details
|
||||
- Prioritize files that are central to the research question; skip peripheral files that sub-agents already summarized adequately
|
||||
- This is the step where you build deep understanding — the previous step was just finding what to read
|
||||
|
||||
5. **Synthesize findings into a complete picture:**
|
||||
- Combine your own reading with sub-agent discoveries
|
||||
- Connect findings across different components
|
||||
- Include specific file paths and line numbers for reference
|
||||
- Highlight patterns, connections, and architectural decisions
|
||||
- Answer the user's specific questions with concrete evidence
|
||||
|
||||
6. **Gather metadata for the research document:**
|
||||
- Run `python <skill_directory>/scripts/metadata.py` to get date, commit, branch, and repository info
|
||||
- Determine the output filename: `docs/agents/research/YYYY-MM-DD-description.md`
|
||||
- YYYY-MM-DD is today's date
|
||||
- description is a brief kebab-case description of the research topic
|
||||
- Example: `2025-01-08-authentication-flow.md`
|
||||
- The output folder (`docs/agents/research/`) can be overridden by instructions in the project's `AGENTS.md` or `CLAUDE.md`
|
||||
|
||||
7. **Generate research document:**
|
||||
- Use the metadata gathered in step 5
|
||||
- Ensure the `docs/agents/research/` directory exists (create if needed)
|
||||
- Structure the document with YAML frontmatter followed by content:
|
||||
```markdown
|
||||
---
|
||||
date: [ISO date/time from metadata]
|
||||
git_commit: [Current commit hash from metadata]
|
||||
branch: [Current branch name from metadata]
|
||||
topic: "[User's Question/Topic]"
|
||||
tags: [research, codebase, relevant-component-names]
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Research: [User's Question/Topic]
|
||||
|
||||
## Research Question
|
||||
[Original user query]
|
||||
|
||||
## Summary
|
||||
[High-level documentation of what was found, answering the user's question by describing what exists]
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### [Component/Area 1]
|
||||
- Description of what exists (file.ext:line)
|
||||
- How it connects to other components
|
||||
- Current implementation details (without evaluation)
|
||||
|
||||
### [Component/Area 2]
|
||||
...
|
||||
|
||||
## Code References
|
||||
- `path/to/file.py:123` - Description of what's there
|
||||
- `another/file.ts:45-67` - Description of the code block
|
||||
|
||||
## Architecture Documentation
|
||||
[Current patterns, conventions, and design implementations found in the codebase]
|
||||
|
||||
## Open Questions
|
||||
[Any areas that need further investigation]
|
||||
```
|
||||
|
||||
8. **Present findings to the user:**
|
||||
- Present a concise summary of findings
|
||||
- Include key file references for easy navigation
|
||||
- Ask if they have follow-up questions or need clarification
|
||||
|
||||
9. **Handle follow-up questions:**
|
||||
- If the user has follow-up questions, append to the same research document
|
||||
- Add a new section: `## Follow-up Research [timestamp]`
|
||||
- Spawn new sub-agents as needed for additional investigation
|
||||
- Continue updating the document
|
||||
|
||||
## Important notes:
|
||||
- Use parallel sub-agents for file discovery and landscape mapping, but **read the most important files yourself** in the main context
|
||||
- Sub-agents are scouts that find relevant files — the main agent must read key files to build deep understanding
|
||||
- Do NOT rely solely on sub-agent summaries for your core findings; they may miss nuances and connections
|
||||
- Focus on finding concrete file paths and line numbers for developer reference
|
||||
- Research documents should be self-contained with all necessary context
|
||||
- Each sub-agent prompt should be specific and focused on locating files and reporting back paths
|
||||
- Document cross-component connections and how systems interact
|
||||
- **CRITICAL**: You and all sub-agents are documentarians, not evaluators
|
||||
- **REMEMBER**: Document what IS, not what SHOULD BE
|
||||
- **NO RECOMMENDATIONS**: Only describe the current state of the codebase
|
||||
- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
|
||||
- **Critical ordering**: Follow the numbered steps exactly
|
||||
- ALWAYS read mentioned files first before spawning sub-tasks (step 1)
|
||||
- ALWAYS read key files yourself after sub-agents report back (step 4)
|
||||
- ALWAYS wait for your own reading to complete before synthesizing (step 5)
|
||||
- ALWAYS gather metadata before writing the document (step 6 before step 7)
|
||||
- NEVER write the research document with placeholder values
|
||||
39
.claude/skills/rpi-research/scripts/metadata.py
Executable file
39
.claude/skills/rpi-research/scripts/metadata.py
Executable file
@@ -0,0 +1,39 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Get git metadata for research documents."""
|
||||
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def run(cmd: list[str]) -> str:
|
||||
result = subprocess.run(cmd, capture_output=True, text=True)
|
||||
return result.stdout.strip() if result.returncode == 0 else ""
|
||||
|
||||
|
||||
def get_repo_name() -> str:
|
||||
remote = run(["git", "remote", "get-url", "origin"])
|
||||
if remote:
|
||||
# Handle both HTTPS and SSH URLs
|
||||
name = remote.rstrip("/").rsplit("/", 1)[-1]
|
||||
return name.removesuffix(".git")
|
||||
# Fall back to directory name
|
||||
root = run(["git", "rev-parse", "--show-toplevel"])
|
||||
return Path(root).name if root else Path.cwd().name
|
||||
|
||||
|
||||
def main() -> None:
|
||||
metadata = {
|
||||
"date": datetime.now(timezone.utc).isoformat(),
|
||||
"commit": run(["git", "rev-parse", "HEAD"]),
|
||||
"branch": run(["git", "branch", "--show-current"]),
|
||||
"repository": get_repo_name(),
|
||||
}
|
||||
json.dump(metadata, sys.stdout, indent=2)
|
||||
print()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user