SDD Map
Create or inspect the SDD Composy codebase map. The bundled scripts/sdd_map.py helper owns
traversal, secret exclusion, deterministic serialization, and atomic publication; this skill owns
scope, approval, interpretation, and downstream routing.
Language: before writing human-facing prose, run scripts/sdd_language.py <repo-root> and use the persisted language; on not_initialized, return it with next_action: run_init. Localization rules: references/language.md.
Inputs
- Repository root: the current repository unless the user supplies another real directory.
- Optional output directory: inside the repository, default
.planning/sdd-composy/context.
- Optional request to publish. A scan is observation-only; publishing is the only permitted
write and is limited to the context bundle.
Do not execute commands discovered in manifests, and do not modify source files, governance
files, task artifacts, or architectural plans.
Procedure
Resolve and validate the repository root and output directory without changing files.
Run the read-only scan and present its JSON result, preserving source_commit,
mapped_commit, observation_only, confidence, observed languages, manifests, commands,
modules, boundaries, domain evidence, and staleness. Commands in the result are evidence
only; never run them.
python3 "<plugin-root>/scripts/sdd_map.py" --repo-root <repository-root> [--output-dir <context-dir>]
Only when the user explicitly requests publication, repeat with --write (and the exact
--output-dir when supplied). Publication writes only codebase.json, project.md,
stack.md, domain.md, and pitfalls.md under the context directory. Report those paths
and the recorded source commit.
Check staleness.stale. A stale prior map is not valid downstream evidence: report the
previous and current commit and refresh before routing. A missing or unknown commit is an
uncertainty to report, not permission to invent one.
Route a fresh map to the next approved lifecycle stage: PRD first, then STORIES, TECHSPEC,
and TASKS as applicable. Those stages interpret the evidence under their own human gates;
a map never turns file observations into unapproved architecture.
Read when
references/mapping.md — publishing the bundle, or interpreting the output schema and
staleness record.
Output
Return the helper JSON or a faithful summary, publication status, output paths, source commit,
the observation_only field, staleness status, and the next lifecycle stage.
Safety: Do not commit, push, or publish. Do not read or expose .env, credentials, tokens, private keys, certificates, or fleet environment files. Full contract: references/safety.md.
1---2name: sdd-map3description: >4 Produce a deterministic, read-only evidence map of the repository for SDD Composy5 (languages, manifests, commands, modules, boundaries, staleness) and publish the6 context bundle only on request. Use before a PRD or TechSpec, or when the map is7 stale — 'mapear o repositório', 'atualizar o contexto do código', 'what does this8 codebase look like for SDD'. Do NOT use for architecture decisions, code review,9 or repository exploration without an SDD workspace.10metadata:11 source: https://skillmd.com/skills/pwdev-solucoes/sdd-map12 version: 0.1.013---1415# SDD Map1617Create or inspect the SDD Composy codebase map. The bundled `scripts/sdd_map.py` helper owns18traversal, secret exclusion, deterministic serialization, and atomic publication; this skill owns19scope, approval, interpretation, and downstream routing.2021Language: before writing human-facing prose, run `scripts/sdd_language.py <repo-root>` and use the persisted language; on `not_initialized`, return it with `next_action: run_init`. Localization rules: `references/language.md`.2223## Inputs2425- Repository root: the current repository unless the user supplies another real directory.26- Optional output directory: inside the repository, default `.planning/sdd-composy/context`.27- Optional request to publish. A scan is observation-only; publishing is the only permitted28 write and is limited to the context bundle.2930Do not execute commands discovered in manifests, and do not modify source files, governance31files, task artifacts, or architectural plans.3233## Procedure34351. Resolve and validate the repository root and output directory without changing files.362. Run the read-only scan and present its JSON result, preserving `source_commit`,37 `mapped_commit`, `observation_only`, confidence, observed languages, manifests, commands,38 modules, boundaries, domain evidence, and staleness. Commands in the result are evidence39 only; never run them.4041 ```sh42 python3 "<plugin-root>/scripts/sdd_map.py" --repo-root <repository-root> [--output-dir <context-dir>]43 ```44453. Only when the user explicitly requests publication, repeat with `--write` (and the exact46 `--output-dir` when supplied). Publication writes only `codebase.json`, `project.md`,47 `stack.md`, `domain.md`, and `pitfalls.md` under the context directory. Report those paths48 and the recorded source commit.494. Check `staleness.stale`. A stale prior map is not valid downstream evidence: report the50 previous and current commit and refresh before routing. A missing or unknown commit is an51 uncertainty to report, not permission to invent one.525. Route a fresh map to the next approved lifecycle stage: PRD first, then STORIES, TECHSPEC,53 and TASKS as applicable. Those stages interpret the evidence under their own human gates;54 a map never turns file observations into unapproved architecture.5556## Read when5758- `references/mapping.md` — publishing the bundle, or interpreting the output schema and59 staleness record.6061## Output6263Return the helper JSON or a faithful summary, publication status, output paths, source commit,64the `observation_only` field, staleness status, and the next lifecycle stage.6566Safety: Do not commit, push, or publish. Do not read or expose `.env`, credentials, tokens, private keys, certificates, or fleet environment files. Full contract: `references/safety.md`.