From maproom
Search SDD spec directories using maproom for tickets, epics, planning docs, and architecture decisions.
npx claudepluginhub manifoldlogic/claude-code-plugins --plugin maproomThis skill uses the workspace's default tool permissions.
This skill documents how to use maproom to search SDD (Spec-Driven Development) specification directories for tickets, epics, planning documents, and architecture decisions. It extends the general-purpose `maproom-search` skill with SDD-specific patterns, directory structure knowledge, and search strategies tailored to spec content.
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
This skill documents how to use maproom to search SDD (Spec-Driven Development) specification directories for tickets, epics, planning documents, and architecture decisions. It extends the general-purpose maproom-search skill with SDD-specific patterns, directory structure knowledge, and search strategies tailored to spec content.
SDD specs live in a separate directory tree from source code, pointed to by the SDD_ROOT_DIR environment variable. When this directory has been indexed by maproom, agents can use semantic search to find design rationale, ticket history, planning context, and architecture decisions without reading every file manually.
This skill does not duplicate general maproom command syntax or setup instructions. For command reference, first-time setup, and troubleshooting, see the maproom-search skill referenced below.
Apply this skill when:
Decision: maproom vs Grep vs Glob for specs
| Situation | Tool | Why |
|---|---|---|
| Know the ticket ID exactly | Grep or Glob | Direct file lookup is faster than search |
| Know the exact file path | Read | No search needed |
| Looking for a concept across specs | maproom vector-search | Semantic match across all indexed spec content |
| Looking for a specific term in specs | maproom search (FTS) | Exact term matching across indexed chunks |
| Spec repo not indexed in maproom | Grep + Glob | Fallback to file-level search tools |
| Searching within a single known ticket directory | Grep | Scoped search is more efficient |
Before using maproom for SDD spec search, verify two conditions:
Step 1: Verify SDD_ROOT_DIR is set
echo "$SDD_ROOT_DIR"
If empty, SDD_ROOT_DIR was not configured. The SDD plugin's setup-sdd-env.js hook sets this at session start. It defaults to /app/.sdd but is typically overridden in .claude/settings.json to point to the project's spec directory (e.g., /workspace/_SPECS/claude-code-plugins).
Step 2: Verify the spec repo is indexed in maproom
maproom status
Look for a repository entry whose path matches or contains SDD_ROOT_DIR. If no matching repository appears, the spec directory has not been scanned. See the Fallback section below.
Step 3: Identify the maproom repo name
The maproom repo name is assigned during maproom scan --repo <name>. It does not follow a fixed formula. Use maproom status to find the repo name whose worktree path matches SDD_ROOT_DIR.
Example: If SDD_ROOT_DIR=/workspace/_SPECS/claude-code-plugins and status shows:
Repository: claude-code-plugins-specs
Worktree: main
Path: /workspace/_SPECS/claude-code-plugins
Chunks: 850
Then use --repo claude-code-plugins-specs in search commands.
The spec directory under SDD_ROOT_DIR contains the following structure:
{SDD_ROOT_DIR}/
├── epics/
│ └── {DATE}_{name}/ # or {DATE}_{jira_id}_{name}/
│ ├── overview.md # Vision, scope, success signals
│ ├── decisions.md # Running decision log
│ ├── backlog.md # Ideas not yet tickets
│ ├── analysis/
│ │ ├── opportunity-map.md # Problem spaces, goals, constraints
│ │ ├── domain-model.md # Core entities and boundaries
│ │ └── research-synthesis.md # Key findings, open questions
│ ├── decomposition/
│ │ ├── multi-ticket-overview.md # Ticket execution order
│ │ └── ticket-summaries/ # Per-ticket summaries
│ └── reference/ # External reference materials
├── tickets/
│ └── {TICKET_ID}_{name}/
│ ├── README.md # Ticket overview and status
│ ├── planning/
│ │ ├── analysis.md # Problem analysis
│ │ ├── prd.md # Product Requirements Document
│ │ ├── architecture.md # Solution design and decisions
│ │ ├── plan.md # Execution plan with phases
│ │ ├── quality-strategy.md # Testing approach and coverage
│ │ └── security-review.md # Security assessment
│ ├── tasks/
│ │ └── {TASK_ID}_{name}.md # Individual task files
│ └── deliverables/ # Work products
├── archive/
│ ├── tickets/ # Completed tickets
│ └── epics/ # Completed epics
├── reference/ # Shared reference templates
├── research/ # Research materials
├── scratchpad/ # Working notes
└── logs/ # Execution logs
| Content Type | Recommended Search | Why |
|---|---|---|
Ticket by ID (e.g., APIV2) | FTS search | Ticket IDs are exact identifiers |
Section headings (Risk Assessment) | FTS search | Heading text is literal |
| Architecture decisions | vector-search | Decisions use varied natural language |
| Design rationale ("why was X built this way") | vector-search | Intent-based queries need semantic matching |
| Acceptance criteria for a feature | vector-search | Criteria phrasing varies across tickets |
| Planning doc by known term | FTS search | Known terms match directly |
| Quality strategy patterns | vector-search | Testing approaches described conceptually |
| Task files for a specific ticket | FTS search | Task IDs are exact identifiers |
| Cross-ticket dependency analysis | vector-search | Dependencies described in natural language |
Rule of thumb: If you have an ID or exact term, use FTS. If you have a question or concept, use vector search. This mirrors the general guidance in maproom-search but applies specifically to spec document types.
SDD_ROOT_DIR from environmentIf maproom status does not show the spec directory, fall back to Grep and Glob:
Find a ticket by ID:
# Using Glob to find the ticket directory
# Pattern: {SDD_ROOT_DIR}/tickets/{TICKET_ID}_*
Use the Glob tool with pattern tickets/APIV2_*/**/*.md under SDD_ROOT_DIR.
Search across all planning docs:
Use the Grep tool with the search pattern across SDD_ROOT_DIR, filtering to *.md files.
Find architecture decisions:
Use the Grep tool searching for "Decision" or "Rationale" in planning/architecture.md files under SDD_ROOT_DIR.
The fallback approach is slower and less precise than maproom search but works without any indexing setup.
If maproom status shows multiple repos with overlapping paths:
SDD_ROOT_DIR/workspace/_SPECS//workspace/_SPECS/claude-code-plugins//workspace/_SPECS/claude-code-pluginsSee multi-repo-guide.md for advanced path resolution patterns.
maproomnpm install -g @crewchief/maproom) or use fallback Grep/Glob search as described in the Fallback section above. See maproom-search skill (plugins/maproom/skills/maproom-search/SKILL.md) for full installation and setup guidance.maproom status to list all indexed repositories and find the correct name matching your SDD_ROOT_DIR path. The repo name is assigned during maproom scan --repo <name> and does not follow a fixed formula.vector-search instead of FTS (or vice versa) based on the FTS vs Vector Search table above. Broaden query terms, remove overly specific identifiers, and verify the repo is indexed with maproom status. If the repo shows zero chunks, re-run maproom scan.echo "$SDD_ROOT_DIR" returns empty or an incorrect pathsetup-sdd-env.js hook.claude/settings.json for the SDD_ROOT_DIR setting. The hook (plugins/sdd/hooks/setup-sdd-env.js) reads this value at session start and exports it. If the setting is missing, ask the developer to add it to their project's .claude/settings.json.ls -la "$SDD_ROOT_DIR". Ensure the current user has read access to the directory tree. In containerized environments, verify the volume mount includes appropriate permissions.Context: You need to review the architecture decisions for ticket APIV2 before implementing a task.
Search:
maproom search --repo claude-code-plugins-specs --query "APIV2"
What this finds: All chunks containing the ticket ID, including the README, planning documents, and task files. Results include heading_1, heading_2, and markdown_section chunks from the ticket's directory.
Follow-up: Read the architecture.md file from the search results to get the full design context:
maproom search --repo claude-code-plugins-specs --query "APIV2 architecture decision rationale"
Note: Example repo names like
claude-code-plugins-specsare placeholders. Replace with your actual repo name frommaproom status. The repo name must match yourSDD_ROOT_DIRpath.
Context: You are about to redesign the plugin system and want to find any prior architecture decisions related to plugins.
Search:
maproom vector-search --repo claude-code-plugins-specs --query "plugin system design decisions"
Why vector search: The query describes a concept. Different tickets may use varied terminology ("plugin architecture", "extension system", "hook framework") that vector search can match semantically.
Narrowing results: If results span too many tickets, add more specific terms:
maproom vector-search --repo claude-code-plugins-specs --query "plugin loading registration lifecycle"
Context: You want to find all tickets that dealt with authentication or authorization to understand the evolution of the auth system.
Search:
maproom vector-search --repo claude-code-plugins-specs --query "authentication authorization security access control"
Follow-up with FTS: After identifying relevant ticket IDs from vector search results, use FTS to find their specific task files:
maproom search --repo claude-code-plugins-specs --query "AUTHZ"
Context: You are starting a new epic and want to see how previous epics structured their research and domain analysis.
Search:
maproom vector-search --repo claude-code-plugins-specs --query "domain model entities boundaries research synthesis"
What this finds: Chunks from analysis/domain-model.md and analysis/research-synthesis.md files across epics, showing how prior work structured domain analysis.
Alternative with FTS for specific epic content:
maproom search --repo claude-code-plugins-specs --query "opportunity map constraints"
Context: You need to write a quality strategy for a new ticket and want to reference how testing was approached in similar tickets.
Search:
maproom vector-search --repo claude-code-plugins-specs --query "testing strategy coverage requirements quality gates"
What this finds: Chunks from planning/quality-strategy.md files across tickets, showing testing approaches, coverage thresholds, and quality gate definitions used in prior work.
maproom-search (plugins/maproom/skills/maproom-search/SKILL.md) - General maproom command reference, first-time setup, search type guidance, troubleshooting, and multi-repo search patternsmulti-repo-guide (plugins/maproom/skills/maproom-search/references/multi-repo-guide.md) - Cross-repo search strategies, chunk kinds by repo type, and configuration setup guideplugins/sdd/hooks/setup-sdd-env.js - How SDD_ROOT_DIR is set at session startplugins/sdd/skills/project-workflow/scripts/scaffold-ticket.sh - Ticket directory structure and planning doc templatesplugins/sdd/skills/project-workflow/scripts/scaffold-epic.sh - Epic directory structure and analysis doc templates.claude/settings.json - Where SDD_ROOT_DIR is configured per-project