Guided codebase discovery that produces a structured, shareable factual context brief for use by downstream skills.
From workflow-orchestrationnpx claudepluginhub mikecubed/agent-orchestration --plugin workflow-orchestrationThis skill uses the workspace's default tool permissions.
Implements Clean Architecture in Android and Kotlin Multiplatform projects: module layouts, dependency rules, UseCases, Repositories, domain models, and data layers with Room, SQLDelight, Ktor.
Provides process, architecture, review, hiring, and testing guidelines for engineering teams relying on AI code generation.
Delivers DB-free sandbox API regression tests for Next.js/Vitest to catch AI blind spots in self-reviewed code changes like API routes and backend logic.
Use this skill when a developer or agent needs to understand an unfamiliar codebase before planning, implementing, debugging, or reviewing. It runs a structured discovery pass and produces a factual context brief that downstream skills can consume directly, avoiding redundant exploration.
Persistent team, squad, or fleet-style long-lived orchestration is out of scope for this skill. Use a separate orchestration layer if persistent coordination is needed.
Activate when the developer asks for things like:
Also activate when:
/workflow-orchestration:planning-orchestration, /workflow-orchestration:systematic-debugging, or /workflow-orchestration:architecture-review;Before you start, identify:
.agent/codebase-brief.md);If any critical inputs are missing, ask the developer before proceeding.
Use separate roles for:
In Claude Code, spawn each scout as a separate agent using the Agent tool. Pass each scout a scoped prompt limited to its discovery dimension. The coordinator merges results into the factual context brief. Do not allow scouts to make recommendations or judgments — they gather facts only.
Resolve the active model for each role using this priority chain:
Project config — look for the runtime-specific config file in the current project root:
.copilot/models.yaml.claude/models.yamlThese are plain YAML files (no markdown, no fenced blocks). Read the implementer, reviewer, and scout keys directly. If a key is absent, fall back to the baked-in default for that role — do not re-prompt for a key that is missing.
Session cache — if models were already confirmed earlier in this session, reuse them without asking again.
Baked-in defaults — if neither config file nor session cache exists, show the defaults below, ask the user to confirm or override them once, then cache the answer for the rest of the session.
| Runtime | Role | Default model |
|---|---|---|
| Copilot CLI | Implementer | claude-opus-4.6 |
| Copilot CLI | Reviewer | gpt-5.4 |
| Copilot CLI | Scout | claude-haiku-4.5 |
| Claude Code | Implementer | claude-opus-4.6 |
| Claude Code | Reviewer | claude-opus-4.6 |
| Claude Code | Scout | claude-haiku-4.5 |
Before launching discovery:
.agent/codebase-brief.md);Run 5 scout agents in parallel, one per dimension. Each scout gathers only factual information and returns a structured section.
Dimension 1 — Structure
Dimension 2 — Dependencies
Dimension 3 — Tests
Dimension 4 — Architecture
Dimension 5 — Hotspots
git log --since);Each scout returns its results in a structured text block. If a dimension fails or times out, the coordinator records the failure and continues with the remaining dimensions.
The coordinator merges all dimension results into a single document:
Write the merged brief to the confirmed output path. If the write fails, try the fallback path docs/codebase-brief.md. Record the actual path used.
Write .agent/SESSION.md using the full schema defined in docs/session-md-schema.md:
current-task: "Map codebase and produce factual context brief"
current-phase: "codebase-mapped"
next-action: "ready for architecture-review or planning"
workspace: "<repository root or subtree>"
last-updated: "<ISO-8601 datetime>"
Required sections:
## Decisions — record brief-path: <actual output path> and any scope narrowing decisions## Files Touched — the brief file path## Open Questions — any dimensions that returned incomplete results## Blockers — empty if none## Failed Hypotheses — dimensions that failed or timed outIf the SESSION.md write fails: log a warning and continue. Do not block workflow completion.
All 5 discovery dimensions must be attempted. A dimension that fails or times out counts as attempted but must be recorded in the brief with a failure note.
The factual brief artifact must be written to disk. If both the primary and fallback paths fail, the gate fails.
The brief-path must be recorded in SESSION.md ## Decisions so downstream skills can locate the brief. This is a durable artifact requirement — the brief-path entry is how architecture-review and other skills find the context.
Before declaring the mapping complete, confirm ALL of the following. Any failing item blocks the "mapping complete" declaration.
If any item is FAIL: report the failing item(s) by name, state what must be done to resolve each, and do not advance past the gate.
When stopping, ensure any partial results are preserved as a durable artifact so work is not lost.
Developer: map this codebase so we can plan the v2 migration
# Codebase Brief — my-app
**Repository:** /home/user/projects/my-app
**Timestamp:** 2025-07-20T14:30:00Z
**Dimensions:** 5/5 completed
**Scope:** full repository
## Structure
- Root: Node.js project (package.json, tsconfig.json)
- Entry points: src/index.ts, src/cli.ts
- Build: npm run build (tsc)
- Test: npm test (vitest)
- Lint: npm run lint (eslint)
## Dependencies
- 12 production dependencies (express, zod, prisma, ...)
- 8 dev dependencies (vitest, typescript, eslint, ...)
- Internal modules: src/api/ imports src/services/, src/services/ imports src/db/
## Tests
- Framework: vitest
- Test files: 24 files in test/ and **/*.test.ts
- Coverage: 78% line coverage configured
- Status: 142 passing, 0 failing, 3 skipped
## Architecture
- Layers: api (controllers) → services → db (repositories)
- Naming: camelCase functions, PascalCase classes, kebab-case files
- Public API: REST endpoints in src/api/routes/
- Config: dotenv with .env and .env.example
## Hotspots
- Most changed (90d): src/services/auth.ts (47 commits), src/api/routes/users.ts (31 commits)
- Largest files: src/db/migrations/001_init.sql (820 lines), src/services/auth.ts (412 lines)
- TODO density: 14 TODOs, 3 FIXMEs — concentrated in src/services/