Skip to content

Commit d2ad7d8

Browse files
juanklagosjuanklagos
committed
docs(structure): add project organization map
1 parent 103c7f4 commit d2ad7d8

5 files changed

Lines changed: 693 additions & 2 deletions

File tree

‎README.es.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,9 @@ flowchart LR
128128

129129
## 🏗️ Anatomía de un proyecto SDD
130130

131+
Mapa completo carpeta por carpeta:
132+
- [docs/es/42-mapa-organizacion-proyecto.md](./docs/es/42-mapa-organizacion-proyecto.md)
133+
131134
Carpetas obligatorias:
132135
- `idea/`: intención y alcance del proyecto
133136
- `specs/`: especificaciones numeradas
@@ -180,6 +183,7 @@ Paquete obligatorio por feature:
180183
- Setup clientes: [Recetas](./docs/es/36-recetas-setup-clientes.md)
181184
- Versionado: [Estrategia](./docs/es/37-estrategia-versionado.md)
182185
- Roadmap: [Roadmap público](./docs/es/35-roadmap-publico.md)
186+
- Organización: [Mapa del proyecto](./docs/es/42-mapa-organizacion-proyecto.md)
183187
- Kit de medios: [Assets y posicionamiento](./docs/es/38-kit-medios.md)
184188
- Preparación próxima release: [v1.2.0](./docs/es/39-preparacion-v1.2.0.md)
185189
- Calidad: [Checklists por etapa](./docs/es/21-checklists-calidad-por-etapa.md) · [ADR](./docs/es/24-decisiones-de-arquitectura.md)

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,9 @@ flowchart LR
128128

129129
## 🏗️ Anatomy of an SDD Project
130130

131+
Full folder-by-folder map:
132+
- [docs/en/42-project-organization-map.md](./docs/en/42-project-organization-map.md)
133+
131134
Mandatory folders:
132135
- `idea/`: project intent and scope
133136
- `specs/`: numbered specifications
@@ -180,6 +183,7 @@ Mandatory spec bundle (for each feature):
180183
- Client Setup: [Recipes](./docs/en/36-client-setup-recipes.md)
181184
- Versioning: [Strategy](./docs/en/37-versioning-strategy.md)
182185
- Roadmap: [Public Roadmap](./docs/en/35-public-roadmap.md)
186+
- Organization: [Project Map](./docs/en/42-project-organization-map.md)
183187
- Media Kit: [Assets and Positioning](./docs/en/38-media-kit.md)
184188
- Next Release Prep: [v1.2.0](./docs/en/39-v1.2.0-preparation.md)
185189
- Quality: [Stage Checklists](./docs/en/21-quality-checklists-by-stage.md) · [ADR](./docs/en/24-architecture-decisions.md)

‎docs/README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ flowchart LR
5555
- Next release prep: [EN](./en/39-v1.2.0-preparation.md) | [ES](./es/39-preparacion-v1.2.0.md)
5656
- Command results reference: [EN](./en/40-command-results-reference.md) | [ES](./es/40-referencia-resultados-comandos.md)
5757
- Complete MCP reference: [EN](./en/41-complete-mcp-reference.md) | [ES](./es/41-referencia-completa-mcp.md)
58+
- Project organization map: [EN](./en/42-project-organization-map.md) | [ES](./es/42-mapa-organizacion-proyecto.md)
5859
- Continuous refinement: [EN](./en/11-continuous-refinement.md) | [ES](./es/11-refinamiento-continuo.md)
5960
- Quality checklists: [EN](./en/21-quality-checklists-by-stage.md) | [ES](./es/21-checklists-calidad-por-etapa.md)
6061

@@ -64,8 +65,8 @@ flowchart LR
6465
- Validated prompt bank: [EN](./en/26-validated-prompt-bank.md) | [ES](./es/26-banco-prompts-validados.md)
6566

6667
## Full index / Índice completo
67-
- EN docs list: `docs/en/00` to `docs/en/41`
68-
- ES docs list: `docs/es/00` to `docs/es/41`
68+
- EN docs list: `docs/en/00` to `docs/en/42`
69+
- ES docs list: `docs/es/00` to `docs/es/42`
6970

7071
## Documentation audits / Auditorías de documentación
7172
- EN: [32-documentation-audit-2026-03-14](./en/32-documentation-audit-2026-03-14.md)

‎docs/en/42-project-organization-map.md‎

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
# Project Organization Map
2+
3+
## Purpose
4+
5+
This document explains how the repository is organized at the folder level.
6+
7+
It is not a code map.
8+
It is an operating map for humans and AI agents so they know:
9+
- what belongs in each folder
10+
- what is framework-only
11+
- what is project-runtime material
12+
- what should be edited often
13+
- what should remain stable
14+
15+
## Reading rule
16+
17+
There are two levels to understand:
18+
19+
1. **Framework root**
20+
This repository itself. It contains the reusable SDD framework, MCP server, guides, scripts, and templates.
21+
22+
2. **Target project**
23+
The runnable or adapted project that uses the framework. Inside this repository, the clean default is `./www/<project-name>/`. Outside this repository, the target project can live in another path chosen by the user.
24+
25+
## Organizational map
26+
27+
```mermaid
28+
flowchart TD
29+
A["Repository Root"] --> B["idea/"]
30+
A --> C["specs/"]
31+
A --> D["bitacora/"]
32+
A --> E["docs/"]
33+
A --> F["scripts/"]
34+
A --> G["template-context/"]
35+
A --> H["templates/"]
36+
A --> I["packages/"]
37+
A --> J["examples/"]
38+
A --> K["playbooks/"]
39+
A --> L["quality/"]
40+
A --> M["legal/"]
41+
A --> N["www/"]
42+
A --> O[".github/"]
43+
A --> P[".githooks/"]
44+
```
45+
46+
## Folder-by-folder explanation
47+
48+
### `idea/`
49+
50+
Role:
51+
- global project intent
52+
53+
What belongs here:
54+
- the main project definition
55+
- the problem, goal, scope, audience, risks, and completion criteria
56+
57+
Main file:
58+
- `idea/IDEA_GENERAL.md`
59+
60+
When to update:
61+
- when the overall project direction changes
62+
63+
### `specs/`
64+
65+
Role:
66+
- feature-level planning and execution backbone
67+
68+
What belongs here:
69+
- the spec index
70+
- the reusable spec template bundle
71+
- one numbered folder per feature or workstream
72+
73+
Important contents:
74+
- `specs/INDEX.md`
75+
- `specs/README.md`
76+
- `specs/_template/`
77+
- `specs/001-.../`
78+
- `specs/002-.../`
79+
80+
When to update:
81+
- every time a new feature is defined
82+
- every time scope, plan, tasks, or history change
83+
84+
### `bitacora/`
85+
86+
Role:
87+
- traceability and session memory
88+
89+
What belongs here:
90+
- global project log
91+
- daily logs
92+
- handoffs
93+
- decision records
94+
- reusable logging templates
95+
96+
Subfolders:
97+
- `bitacora/global/`
98+
- `bitacora/diaria/`
99+
- `bitacora/handoffs/`
100+
- `bitacora/decisiones/`
101+
- `bitacora/templates/`
102+
103+
When to update:
104+
- at session close
105+
- when an important decision is made
106+
- when another agent or operator must continue the work
107+
108+
### `docs/`
109+
110+
Role:
111+
- user documentation and framework guidance
112+
113+
What belongs here:
114+
- onboarding docs
115+
- guides by level
116+
- MCP docs
117+
- roadmap, launch, versioning, legal references, and support material
118+
119+
Important subfolders:
120+
- `docs/en/`
121+
- `docs/es/`
122+
- `docs/assets/`
123+
124+
When to update:
125+
- when the framework behavior changes
126+
- when user-facing instructions become outdated
127+
128+
### `scripts/`
129+
130+
Role:
131+
- executable automation for the framework
132+
133+
What belongs here:
134+
- initialization scripts
135+
- validation scripts
136+
- status and roadmap generators
137+
- MCP smoke and integration tests
138+
139+
Examples:
140+
- `create-www-project.sh`
141+
- `init-project.sh`
142+
- `validate-sdd.sh`
143+
- `check-sdd-policy.sh`
144+
- `check-sdd-gate.sh`
145+
146+
When to update:
147+
- when the operational workflow changes
148+
- when automation needs to become safer or more consistent
149+
150+
### `template-context/`
151+
152+
Role:
153+
- core operating instructions for AI agents
154+
155+
What belongs here:
156+
- cross-agent rules
157+
- anti-misuse guidance
158+
- execution gate guidance
159+
- handoff expectations
160+
- prompt accelerators
161+
162+
Important subfolders:
163+
- `template-context/core-instructions/`
164+
- `template-context/prompts/`
165+
166+
When to update:
167+
- when AI behavior expectations change
168+
- when new agent rules must be standardized
169+
170+
### `templates/`
171+
172+
Role:
173+
- reusable writing templates for SDD artifacts
174+
175+
What belongs here:
176+
- idea templates
177+
- spec templates
178+
- bitacora templates
179+
180+
Subfolders:
181+
- `templates/idea/`
182+
- `templates/spec/`
183+
- `templates/bitacora/`
184+
185+
When to update:
186+
- when the standard wording or structure of reusable artifacts changes
187+
188+
### `packages/`
189+
190+
Role:
191+
- productized implementation layer
192+
193+
What belongs here:
194+
- typed reusable code
195+
- MCP server package
196+
197+
Subfolders:
198+
- `packages/sdd-core/`
199+
- `packages/sdd-mcp/`
200+
201+
Meaning:
202+
- `sdd-core` contains reusable logic
203+
- `sdd-mcp` exposes that logic to AI clients through MCP
204+
205+
When to update:
206+
- when framework behavior changes in code
207+
- when MCP tools, resources, prompts, or transports evolve
208+
209+
### `examples/`
210+
211+
Role:
212+
- worked examples for adoption
213+
214+
What belongs here:
215+
- example projects
216+
- example adaptations
217+
- end-to-end example flows
218+
219+
When to update:
220+
- when you need clearer teaching material
221+
- when a new usage pattern should be demonstrated
222+
223+
### `playbooks/`
224+
225+
Role:
226+
- accelerators by project type
227+
228+
What belongs here:
229+
- domain-specific guidance for SaaS, e-commerce, mobile, backend API, and similar contexts
230+
231+
When to update:
232+
- when a project category needs more direct operating help
233+
234+
### `quality/`
235+
236+
Role:
237+
- quality evidence and verification support
238+
239+
What belongs here:
240+
- evidence templates
241+
- quality-oriented support material
242+
243+
Important path:
244+
- `quality/evidence/`
245+
246+
When to update:
247+
- when the framework needs stronger verification standards
248+
249+
### `legal/`
250+
251+
Role:
252+
- licensing and legal framing
253+
254+
What belongs here:
255+
- legal materials and license-related references
256+
257+
When to update:
258+
- when the legal posture of the framework changes
259+
260+
### `www/`
261+
262+
Role:
263+
- managed runtime space for target projects inside this repository
264+
265+
What belongs here:
266+
- runnable projects created with the framework’s default workspace convention
267+
268+
Example:
269+
- `www/my-project/`
270+
271+
Meaning:
272+
- this is not framework source
273+
- this is where target project work should live if it stays inside this repository
274+
275+
When to update:
276+
- whenever a new managed target project is created
277+
278+
### `.github/`
279+
280+
Role:
281+
- repository automation and collaboration config
282+
283+
What belongs here:
284+
- workflows
285+
- issue templates
286+
- GitHub-specific instructions
287+
288+
Important subfolders:
289+
- `.github/workflows/`
290+
- `.github/ISSUE_TEMPLATE/`
291+
292+
When to update:
293+
- when CI, issue intake, or GitHub behavior changes
294+
295+
### `.githooks/`
296+
297+
Role:
298+
- local Git hook automation
299+
300+
What belongs here:
301+
- hook scripts used to enforce validation before commits
302+
303+
When to update:
304+
- when local guardrails need to change
305+
306+
## What should usually remain stable
307+
308+
These areas are framework structure and should not change casually:
309+
- `template-context/`
310+
- `templates/`
311+
- `packages/`
312+
- `scripts/`
313+
- `docs/`
314+
- `.github/`
315+
316+
## What changes frequently during real project work
317+
318+
These areas move most during normal usage:
319+
- `idea/`
320+
- `specs/`
321+
- `bitacora/`
322+
- `www/<project-name>/`
323+
324+
## Practical interpretation for AI agents
325+
326+
- If the task is about improving the framework itself, work in the repository root structure.
327+
- If the task is about a user project, work in the target project path.
328+
- If that target project lives inside this repository, use `www/<project-name>/` as the clean default.
329+
- Never mix runnable project implementation into the framework root.
330+
331+
## Short summary
332+
333+
- `idea/` explains the project.
334+
- `specs/` defines the work.
335+
- `bitacora/` preserves the trace.
336+
- `docs/` teaches the system.
337+
- `scripts/` automate the system.
338+
- `template-context/` instructs AI behavior.
339+
- `templates/` standardize reusable artifacts.
340+
- `packages/` implement the productized core and MCP.
341+
- `www/` hosts managed runnable projects inside this repo.

0 commit comments

Comments
 (0)