84 lines
5.4 KiB
Markdown
84 lines
5.4 KiB
Markdown
---
|
|
name: boo-mapping-project-context
|
|
description: >
|
|
Produces or refreshes a complete context map of a project: structure, entry
|
|
points, services, data flow, conventions, dependencies, deploy surface. Use
|
|
for onboarding into an unfamiliar repo, refreshing stale context docs, "what
|
|
is this project," "map out the codebase," and pre-work recon before planning.
|
|
Do NOT use for evaluating architecture quality; use boo-analyzing-architecture.
|
|
Do NOT use for finding specific bugs; use boo-investigating-failures.
|
|
allowed-tools: Read, Glob, Grep, Bash(tree*), Agent, mcp__boocontext
|
|
metadata:
|
|
version: "1.1"
|
|
---
|
|
|
|
# Mapping Project Context
|
|
|
|
## Size
|
|
|
|
Classify small/medium/large from repo size, number of subsystems, and deployment complexity. Default: small (single-service, single deploy surface). Accept `$size` override.
|
|
|
|
## Process
|
|
|
|
1. If the `boocontext` MCP tools are available (check for `boocontext_overview`), lead with them: `boocontext_overview` for routes/schema/components/dependency graph, then `boocontext_map` for the context map. They produce the structural backbone faster than hand enumeration. Treat their output as codebase-trust evidence (it reads the code), and still verify the verdict envelope (`SAFE`/`CAUTION`/`UNSAFE`) before trusting a result. If the tools are absent, enumerate from disk instead (steps 2-3).
|
|
2. Enumerate from disk to fill gaps boocontext does not cover (deploy surface, CI, env/config files, compose): run `tree`, read package manifests, compose files, configs, and CI files. Trace entry points and service boundaries from code, not from documentation.
|
|
3. Read existing context docs (README, CONTEXT.md, wiki) LAST. Diff them against observed reality and flag drift.
|
|
4. Small = single-pass (produce the context map directly). Medium/large = dispatch `structural-analyst` for module graph analysis (seed it with the boocontext dependency graph when available).
|
|
5. Output the context map with a "Doc drift" section.
|
|
|
|
## What NOT to do
|
|
|
|
- Do not produce recommendations. This skill describes; it does not judge.
|
|
- Roadmap/changelog files are never valid sole evidence. Every claim cites a file read or executed command.
|
|
- Do not read docs before examining the code itself.
|
|
|
|
## Gotchas
|
|
|
|
- **Evidence rule**: codebase citations (file:line) stand alone. Roadmap/changelog files are never sole evidence.
|
|
- **Sizing**: default is small. Only escalate on concrete signals - repo size, subsystem count.
|
|
<!-- standing-rules:pi:start -->
|
|
- **Subagent visibility**: when the Paseo MCP tools (`mcp__paseo__*`) are available, spawn each agent persona as an attached Paseo subagent with `create_agent` (`detached: false`, `notifyOnFinish: true`; for an opencode provider also pass `settings.modeId: "build"` and `settings.features.auto_accept: true`) so every persona appears in the operator's Paseo agent track. Resolve each persona's provider/model from the active preset's `agents` map in `~/.paseo/orchestration-preferences.json`; supervise on the finish notification (never poll) and read each result with `get_agent_activity`.
|
|
- **Subagent fallback**: when the Paseo MCP tools are not available, use the platform's native subagent dispatch. On a platform with no subagent dispatch at all (for example Pi), read each `agents/<name>.md` persona and apply its lens in sequential passes.
|
|
- **Subagent concurrency**: honor the active preset's `concurrency` value in `~/.paseo/orchestration-preferences.json`. When it is `1` (local heavy-weight presets, around 27b/35b or larger on a single llama-swap server), dispatch subagents STRICTLY ONE AT A TIME: launch one, wait for its finish notification and read its result, then launch the next. This overrides any parallel fan-out. Absent or higher `concurrency` means parallel fan-out is fine.
|
|
<!-- standing-rules:pi:end -->
|
|
<!-- standing-rules:core:start -->
|
|
- **No commit**: never commit, push, or stage changes; never `git add -A`. Prove any edits with `git diff --stat`.
|
|
- **No em dashes**: never use em dashes (U+2014) in output or files you write.
|
|
<!-- standing-rules:core:end -->
|
|
- **Doc drift is a finding**: if code contradicts docs, code wins on what the system does today.
|
|
- **Counts must be fresh**: any file or directory count in the report (N skills, N agents, N configs) must come from a command run immediately before writing that line. Counts remembered from earlier in the session produce false drift findings (observed 2026-06-11: a stale glob reported a missing file that existed).
|
|
- **boocontext is optional, not required**: the MCP tools are not registered on every machine or harness. Probe for them; never fail or block when absent, just enumerate from disk. When present, they are an accelerator, not the source of truth: a tool returning `UNSAFE` or empty means fall back, not stop.
|
|
|
|
## Output format
|
|
|
|
```
|
|
# Context Map: <project name>
|
|
|
|
## Structure
|
|
<directory tree or module list>
|
|
|
|
## Services / Ports
|
|
<service name, port, entry point>
|
|
|
|
## Data Stores
|
|
<databases, caches, file stores>
|
|
|
|
## External Dependencies
|
|
<list of external services and their contracts>
|
|
|
|
## Conventions Observed
|
|
<naming, patterns, testing approach, error handling>
|
|
|
|
## Build / Deploy Commands
|
|
<verified by execution where safe>
|
|
|
|
## Doc Drift
|
|
<list of contradictions between docs/reality>
|
|
```
|
|
|
|
## Failure modes
|
|
|
|
- **No repo access**: cannot read the code. Report and stop.
|
|
- **Empty repo**: no files to analyze. Report and stop.
|
|
- **Binary-only repo**: no source code to examine. Report the limitation.
|