diff --git a/README.md b/README.md index b8f9e9b..2f7b3bf 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@

Map any repository into AI-readable context: project map, precedent index, architecture inventory, symbol index, call graph, and docs.
Commands stay in English so they can be copied exactly.
- Live docs: wesleysimplicio.github.io/llm-project-mapper + Live docs: wesleysimplicio.github.io/simplicio-mapper

@@ -100,7 +100,9 @@ delivery loop"] The section below restores the project-specific README material that existed before the globalization pass. Keep this substance when refreshing the top-level narrative: add polish, do not erase operational memory. > 🇺🇸 English. Leia em português: [README.pt-BR.md](README.pt-BR.md). -> Live docs site: [wesleysimplicio.github.io/llm-project-mapper](https://wesleysimplicio.github.io/llm-project-mapper/) +> Live docs site: [wesleysimplicio.github.io/simplicio-mapper](https://wesleysimplicio.github.io/simplicio-mapper/) +> +> The npm package name `@wesleysimplicio/llm-project-mapper` is intentionally retained for historical npm consumers; new releases ship as `simplicio-mapper` on PyPI only (see #87). AI-friendly, stack-neutral repository scaffold. Drop it into **any** project — new or existing — and any agent CLI (Claude Code, Codex, Cursor, GitHub Copilot, Aider with Deepseek/Kimi/MiniMax/GLM, Hermes, OpenClaw) gets the context it needs to ship work the same day. diff --git a/README.pt-BR.md b/README.pt-BR.md index 5cc7952..5c59159 100644 --- a/README.pt-BR.md +++ b/README.pt-BR.md @@ -3,7 +3,7 @@

Mapeie qualquer repositório em contexto legível por IA: project map, precedent index, inventário arquitetural, símbolos, call graph e docs.
Os comandos ficam em inglĂŞs para poder copiar exatamente.
- Docs ao vivo: wesleysimplicio.github.io/llm-project-mapper + Docs ao vivo: wesleysimplicio.github.io/simplicio-mapper

diff --git a/docs-site/docusaurus.config.cjs b/docs-site/docusaurus.config.cjs index 9a8ef41..02d0476 100644 --- a/docs-site/docusaurus.config.cjs +++ b/docs-site/docusaurus.config.cjs @@ -1,10 +1,10 @@ const config = { - title: 'LLM Project Mapper Docs', + title: 'Simplicio Mapper Docs', tagline: 'The docs hub for the scaffold, workflows, and agent operating model.', url: 'https://wesleysimplicio.github.io', - baseUrl: '/llm-project-mapper/', + baseUrl: '/simplicio-mapper/', organizationName: 'wesleysimplicio', - projectName: 'llm-project-mapper', + projectName: 'simplicio-mapper', trailingSlash: false, onBrokenLinks: 'throw', onBrokenAnchors: 'warn', @@ -69,7 +69,7 @@ const config = { respectPrefersColorScheme: true, }, navbar: { - title: 'LLM Project Mapper', + title: 'Simplicio Mapper', items: [ {to: '/', label: 'Docs Home', position: 'left'}, {to: '/quickstart/get-going', label: 'Quickstart', position: 'left'}, @@ -78,7 +78,7 @@ const config = { {to: '/reference/cli-flags', label: 'Reference', position: 'left'}, {type: 'docsVersionDropdown', position: 'right'}, { - href: 'https://github.com/wesleysimplicio/llm-project-mapper', + href: 'https://github.com/wesleysimplicio/simplicio-mapper', label: 'GitHub', position: 'right', }, @@ -111,7 +111,7 @@ const config = { {label: 'Contributing', to: '/community/contributing'}, { label: 'Source Repo', - href: 'https://github.com/wesleysimplicio/llm-project-mapper', + href: 'https://github.com/wesleysimplicio/simplicio-mapper', }, ], }, diff --git a/docs-site/versioned_docs/version-0.7.3/community/_category_.json b/docs-site/versioned_docs/version-0.7.3/community/_category_.json new file mode 100644 index 0000000..dfa8c09 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/community/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Community", + "position": 5, + "collapsible": false, + "collapsed": false +} diff --git a/docs-site/versioned_docs/version-0.7.3/community/contributing.md b/docs-site/versioned_docs/version-0.7.3/community/contributing.md new file mode 100644 index 0000000..8d472db --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/community/contributing.md @@ -0,0 +1,203 @@ +--- +title: Contributing +description: Contribution workflow, review expectations, and Definition of Done. +sidebar_position: 2 +--- +Guia step-by-step para adicionar uma feature, fix ou refactor em `` (``, stack ``). Funciona pra humano e pra agent. Time: ``. + +--- + +## Pré-requisitos + +- Repo clonado, deps instaladas, build verde local. +- Leu `AGENTS.md` (raiz) e `.specs/architecture/PATTERNS.md`. +- Tem acesso a abrir PR e rodar CI. + +--- + +## Fluxo padrão (8 passos) + +### 1. Criar `task.md` em sprint atual + +Toda mudança não-trivial nasce em `task.md`. Caminho: + +``` +.specs/sprints/sprint-XX/-.task.md +``` + +Use `task-template.md` como base. Preencha: +- Contexto e problema. +- Acceptance Criteria testáveis (checkboxes). +- Out of scope explícito. +- Test plan (unit, integration, e2e). +- Definition of Done. +- Pegadinhas conhecidas e links. + +Exemplo: `.specs/sprints/sprint-03/12-magic-link-login.task.md`. + +> Mudança trivial (typo em string, bump patch sem risco, formatação) pode pular task. Mas qualquer coisa que toque comportamento, schema ou UX exige task. + +### 2. Criar branch + +A partir de `main` atualizada: + +```bash +git checkout main +git pull --rebase origin main +git checkout -b feat/magic-link-login +``` + +Convenção de nome em `WORKFLOW.md` seção 1. + +### 3. Implementar seguindo PATTERNS + +- **Não invente padrão novo.** Se `.specs/architecture/PATTERNS.md` define como criar endpoint, componente, teste, hook, repository, siga. +- Mudou padrão? Abra ADR antes (`.specs/architecture/ADR-template.md`). +- Não adicione dependência sem confirmar com `` (perde aprovação técnica e onera bundle/manutenção). +- Edite só o pedido. Sem refactor oportunista. Refactor é PR separado. + +### 4. Testes (unit + e2e) + +Antes do PR, todo verde local: + +```bash +# stack-agnostic - substitua pelo comando real do +npm run lint +npm run test # unit + integration, cobertura >= 80% +npm run test:e2e # Playwright contra ambiente local +``` + +- Bug fix sem teste regressivo é **inaceitável**. Escreva teste que falha sem o fix. +- E2E tem evidência: trace, screenshot, video em `test-results/`. +- Cobertura caiu? Justifica no PR ou adiciona teste. + +### 5. Abrir PR usando template + +Push e abre PR via gh: + +```bash +git push -u origin feat/magic-link-login +gh pr create --fill --web +``` + +Template em `.github/PULL_REQUEST_TEMPLATE.md` é preenchido automático. Complete: +- Link para `task.md`. +- Resumo (3-5 bullets). +- Screenshots/GIF se UI. +- Link pro report E2E (artifact CI). +- Checklist DoD marcada. +- Riscos e rollback. + +Title segue Conventional Commits: `feat(auth): add magic link login`. + +### 6. Review + +- CI verde é pré-requisito. PR com vermelho não vai pra review. +- Reviewer humano em até 4h úteis. PR de hotfix tem SLA 30min. +- Endereça todos `req:` antes de pedir re-review. +- Discussão de design vai no diff. Discussão de arquitetura ampla vira ADR. + +### 7. Merge squash + +Após aprovação: + +```bash +gh pr merge --squash --delete-branch +``` + +Mensagem squash = title do PR. Histórico de `main` fica linear e legível. + +### 8. Deploy + +- Merge em `main` dispara `deploy-staging.yml` automaticamente. +- Verifica smoke em staging (link no Slack pós-deploy). +- Para produção: bump versão e tag SemVer (ver `RELEASE.md`). +- Para mudanças **release-relevant** neste repositório, o padrão é fechar tudo no mesmo ciclo: npm publicado, tag GitHub criada, GitHub Release correspondente e `main` limpa/sincronizada. + +### 9. Fechamento release-relevant neste repositório + +Antes de considerar o trabalho encerrado, executar: + +```bash +npm run lint +npm test +npm run docs:build +npm run test:e2e -- --reporter=list,html +``` + +Se tudo estiver verde: + +```bash +# version + lockfile +npm install --package-lock-only + +# publish +npm publish --access public + +# tag + release +git tag -a vX.Y.Z -m "Release X.Y.Z" +git push origin vX.Y.Z +gh release create vX.Y.Z --title "vX.Y.Z" --notes-file +``` + +Objetivo: evitar divergência entre `package.json`, npm, tags, releases e `main`. + +--- + +## Skills/Agents que você pode usar + +Skills e agents reduzem trabalho repetitivo e enforçam padrão. Ver `.skills/` no repo. + +### Skills disponíveis (em `.skills/`) + +| Skill | Quando trigar | Caminho | +|-------|---------------|---------| +| `playwright-e2e` | Escrever ou ajustar teste E2E. Já tem fixtures, page objects, evidências configuradas. | `.skills/playwright-e2e/SKILL.md` | +| `conventional-commits` | Compor mensagem de commit ou title de PR. Cobre `feat`, `fix`, `chore`, breaking change. | `.skills/conventional-commits/SKILL.md` | +| `_template` | Criar nova skill pro projeto. Ponto de partida com frontmatter e seções. | `.skills/_template/SKILL.md` | + +### Agents customizados (em `.agents/`) + +| Agent | Uso | +|-------|-----| +| `ralph-loop.agent.md` | **Executor autônomo padrão.** Loop `read → plan → execute → lint → unit → Playwright (com evidência) → fix → repeat` até DoD verde. Aciona em toda task técnica. | +| `tdd.agent.md` | TDD specialist. Escreve teste falhando, depois código. Loop red-green-refactor. | +| `reviewer.agent.md` | Code review sem editar. Comenta padrões, sugere melhorias, valida ADRs. | +| `architect.agent.md` | Desenha arquitetura, cria ADRs, não escreve código de produção. | + +> `.agents/` é a fonte canônica (padrão AGENTS.md ecosystem). Espelhado em `.github/copilot/agents/` para o GitHub Copilot Workspace. Detalhes em [`.agents/README.md`](https://github.com/wesleysimplicio/llm-project-mapper/blob/main/.agents/README.md). + +### Como invocar + +- Em Claude Code: `Skill(playwright-e2e)` ou referencia em prompt. +- Em Copilot Agent Mode: seleciona agent custom no chat. +- Skills com trigger explícito tem prefixo `$skill-name` em comentário ou prompt. + +--- + +## Checklist rápido antes do PR + +- [ ] `task.md` criado e linkado. +- [ ] Branch nome segue convenção. +- [ ] Build, lint, unit, e2e verdes local. +- [ ] Cobertura >= 80% (ou justificativa no PR). +- [ ] PATTERNS.md respeitado, ou ADR aberta. +- [ ] Sem dependência nova não-aprovada. +- [ ] PR title em Conventional Commits. +- [ ] Template de PR preenchido com evidências. +- [ ] Sem secrets em diff (`git diff | grep -i 'secret\|token\|key'`). +- [ ] CHANGELOG atualizado se mudança visível ao usuário. + +--- + +## Erros comuns (não faça) + +- Branch que vive 2 semanas: quebra task em pedaços menores. +- PR de 2000 linhas com "vários ajustes": split. +- Test que mocka tudo e não roda lógica real: falso verde. +- Mudar padrão sem ADR: dívida invisível. +- Force-push em branch de PR aberto: reviewer perde contexto. +- Merge com CI vermelho: bloqueia o time inteiro depois. +- Esquecer de remover feature flag concluída: lixo composto. + +Em dúvida, pergunte em `` antes de abrir PR. Custo de pergunta < custo de revert. diff --git a/docs-site/versioned_docs/version-0.7.3/community/showcase.md b/docs-site/versioned_docs/version-0.7.3/community/showcase.md new file mode 100644 index 0000000..4c9329b --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/community/showcase.md @@ -0,0 +1,37 @@ +--- +title: Showcase +description: Examples and templates for projects using LLM Project Mapper. +sidebar_position: 1 +--- +> Real-world projects using LLM Project Mapper. Open a PR adding your project to the table below. + +## How to add yours + +1. Fork this repo. +2. Add a row to the table — keep it alphabetical by project name. +3. Open a PR with title `chore(showcase): add `. +4. PR body must answer: stack, what the agent helped you ship, any lessons learned. + +We do not validate the listed projects beyond "the link works and there is some evidence the starter is in use". Best-effort. + +## Projects + +| Project | Stack | What it does | Author | Notes | +|---|---|---|---|---| +| _your project here_ | _e.g. Next.js + Postgres_ | _one-line description_ | [@you](https://github.com/you) | _agent CLI used_ | + +## Templates + +If you wrote a stack-specific template on top of the starter (a `.skills//SKILL.md`, a preset, a fork tailored for a niche) list it here: + +| Template | Base stack | Maintainer | +|---|---|---| +| _none yet_ | _—_ | _—_ | + +## Reviews & write-ups + +Public blog posts, talks, or videos about using the starter: + +| Format | Title | Author | Link | +|---|---|---|---| +| _none yet_ | _—_ | _—_ | _—_ | diff --git a/docs-site/versioned_docs/version-0.7.3/concepts/_category_.json b/docs-site/versioned_docs/version-0.7.3/concepts/_category_.json new file mode 100644 index 0000000..ea59821 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/concepts/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Concepts", + "position": 3, + "collapsible": false, + "collapsed": false +} diff --git a/docs-site/versioned_docs/version-0.7.3/concepts/architecture-map.md b/docs-site/versioned_docs/version-0.7.3/concepts/architecture-map.md new file mode 100644 index 0000000..ea68cb3 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/concepts/architecture-map.md @@ -0,0 +1,136 @@ +--- +title: Architecture Map Template +description: Template and examples for documenting system boundaries and request flow. +sidebar_position: 2 +--- +Use this file to help agents understand how the system is wired before changing code. + +## System Shape + +- Type: `` +- Frontend: `` +- Backend: `` +- Database: `` +- Jobs/workers: `` +- External integrations: `` + +## Local URLs + +| Service | URL | Notes | +|---|---|---| +| Frontend | `` | `` | +| Backend | `` | `` | + +## Request Path + +Describe the usual end-to-end path: + +```text +Browser/client -> -> -> -> -> -> response +``` + +## Key Directories + +| Directory | Purpose | +|---|---| +| `` | `` | + +## Authentication + +- Flow: `` +- Local/demo credentials: `` +- Token/session storage: `` +- Common failure mode: `` + +## Observability + +- App logs: `` +- API logs: `` +- Job logs: `` +- How to identify current request: `` + +## Deployment + +- Environments: `` +- CI/CD: `` +- Release notes/changelog: `` + +--- + +## EXAMPLE — fictional shop SaaS (delete or copy as a starting point) + +Below is what a real, filled-in version of this file might look like. Use it as a reference for the level of detail an agent expects. + +### System Shape + +- Type: FULLSTACK + MONOREPO +- Frontend: Next.js 14 (App Router, RSC) +- Backend: NestJS 10 (Express adapter) +- Database: Postgres 16 + Redis 7 (cache + queues) +- Jobs/workers: BullMQ workers under `apps/worker/` +- External integrations: Stripe (payments), Mailgun (email), Algolia (search) + +### Local URLs + +| Service | URL | Notes | +|---|---|---| +| Frontend | `http://localhost:3000` | `apps/web` | +| Backend | `http://localhost:4000` | `apps/api`, GraphQL at `/graphql` | +| Worker dashboard | `http://localhost:4001` | Bull board UI | + +### C4 — Container diagram + +```mermaid +graph LR + Browser["Browser"] + CDN["CDN (Vercel)"] + Web["apps/web
Next.js 14"] + API["apps/api
NestJS"] + Worker["apps/worker
BullMQ"] + PG[("Postgres 16
RDS")] + Redis[("Redis 7
ElastiCache")] + Stripe["Stripe"] + Mailgun["Mailgun"] + Algolia["Algolia"] + + Browser --> CDN --> Web + Web -->|REST + GraphQL| API + API --> PG + API --> Redis + API -->|enqueue| Worker + Worker --> PG + Worker --> Redis + Worker --> Mailgun + API --> Stripe + Web -->|search| Algolia +``` + +### Request Path — checkout + +```text +Browser -> /checkout (RSC) -> POST /api/v1/orders -> OrdersController + -> OrdersService.create -> OrdersRepository.insert -> Postgres + -> StripeService.createPaymentIntent -> Stripe API + -> response { order, client_secret } -> Stripe.confirmPayment (browser) + -> webhook POST /webhooks/payment -> orders.completed event -> worker fulfills +``` + +### Authentication + +- Flow: OAuth2 (PKCE) with Auth0 + first-party JWT (15 min) + refresh-token cookie (30 days, httpOnly+secure+sameSite=lax). +- Local/demo credentials: see 1Password vault `shop-saas-dev`. +- Token/session storage: access token in memory, refresh in httpOnly cookie. +- Common failure mode: clock skew with Auth0 — agents must check that workstation clock is synced before debugging 401s. + +### Observability + +- App logs: Vercel runtime logs + `pnpm --filter web dev` stdout. +- API logs: structured JSON to stdout, shipped via Vector to Datadog. +- Job logs: `apps/worker` logs to Datadog with `worker:true` tag. +- How to identify current request: `X-Request-Id` header (UUID v7) — propagated to all downstream calls and added as `request_id` field on every log entry. + +### Deployment + +- Environments: `dev` (preview Vercel per PR), `staging` (auto from `main`), `prod` (manual promote, weekly). +- CI/CD: GitHub Actions `.github/workflows/{ci,deploy-staging,deploy-prod}.yml`. +- Release notes/changelog: `CHANGELOG.md` + GitHub Releases (auto-generated from PR titles). diff --git a/docs-site/versioned_docs/version-0.7.3/concepts/domain-map.md b/docs-site/versioned_docs/version-0.7.3/concepts/domain-map.md new file mode 100644 index 0000000..9342799 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/concepts/domain-map.md @@ -0,0 +1,126 @@ +--- +title: Domain Map Template +description: Template and examples for business entities, rules, and edge cases. +sidebar_position: 3 +--- +Use this file to give agents the shortest reliable path from a user request to the business rule behind it. + +## Product Context + +- App: `` +- Main users: `` +- Main business goal: `` + +## Core Concepts + +| Concept | Meaning | Source of truth | +|---|---|---| +| `` | `` | `` | + +## Critical Rules + +| Rule | Expected behavior | Where implemented | How to test | +|---|---|---|---| +| `` | `` | `` | `` | + +## Main Entities + +| Entity | Description | Storage | +|---|---|---| +| `` | `` | `` | + +## Important Flows + +### `` + +1. User/system action: ``. +2. Entry point: ``. +3. Main modules: ``. +4. Output: ``. +5. Evidence: ``. + +## Edge Cases + +- ``: ``. + +## Open Questions + +- ``: ``. + +--- + +## EXAMPLE — fictional shop SaaS (delete or copy as a starting point) + +### Product Context + +- App: ShopSaaS +- Main users: small-business owners selling physical goods online (Brazil-first). +- Main business goal: maximize gross merchandise volume per active store while keeping support cost per order under R$ 2. + +### Glossary + +| Term | Meaning | +|---|---| +| Store | Tenant. Each store has its own subdomain, settings, and product catalog. | +| Order | A purchase transaction tied to one customer and one or more SKUs. | +| Fulfillment | Picking, packing, and shipping an order. May be in-house or third-party (3PL). | +| Pix | Brazilian instant payment method — settles in ≤ 10s. | +| Boleto | Brazilian bank-issued payment slip, settles in 1-3 business days. | +| Reversal | Either a refund (we initiate) or a chargeback (issuer initiates). | + +### Core Concepts + +| Concept | Meaning | Source of truth | +|---|---|---| +| Order status | Lifecycle state of an order. Enum: `cart`, `pending_payment`, `paid`, `fulfilled`, `shipped`, `delivered`, `refunded`, `disputed`. | `apps/api/src/orders/order.entity.ts` | +| Stock level | Available count per SKU. | `apps/api/src/inventory/inventory.entity.ts`, ground truth in Postgres `inventory` table | +| Idempotency key | UUID supplied by the client to safely retry a mutation. | `apps/api/src/middleware/idempotency.middleware.ts` | + +### Critical Rules + +| Rule | Expected behavior | Where implemented | How to test | +|---|---|---|---| +| Inventory cannot go negative | `POST /orders` returns 422 `out_of_stock` if any item exceeds available. | `OrdersService.checkInventory` | `apps/api/test/orders.spec.ts -> "rejects when stock is 0"` | +| Pix payments accepted only ≤ R$ 50,000 | Above the limit, only credit card or wire are offered. | `apps/api/src/payments/method-selector.ts` | `payments.spec.ts -> "filters pix above 50k"` | +| Refund must be initiated within 90 days | Older orders show "contact support" instead of refund button. | `apps/web/src/features/orders/RefundButton.tsx` | Playwright `e2e/orders-refund.spec.ts` | +| Webhook events processed exactly once | `processed_events` unique constraint on `event_id`. | `apps/api/src/webhooks/dedup.service.ts` | `webhooks.spec.ts -> "duplicate event"` | + +### Main Entities + +```mermaid +erDiagram + STORE ||--o{ PRODUCT : owns + STORE ||--o{ ORDER : receives + CUSTOMER ||--o{ ORDER : places + ORDER ||--|{ ORDER_ITEM : contains + ORDER_ITEM }o--|| PRODUCT : refers + PRODUCT ||--|| INVENTORY : tracked_in + ORDER ||--o| PAYMENT : settled_by + ORDER ||--o{ FULFILLMENT : produces +``` + +| Entity | Description | Storage | +|---|---|---| +| Store | Tenant root. | `stores` table | +| Product | SKU + descriptive metadata. | `products` | +| Inventory | Per-SKU stock count + reservations. | `inventory`, optimistic-locked by `version` | +| Order | One purchase. | `orders` | +| OrderItem | SKU + qty inside an order. | `order_items` | +| Payment | One attempt at collecting an order. May be retried. | `payments` | +| Fulfillment | Picking/shipping batch. | `fulfillments` | + +### Important Flows + +#### Checkout + +1. User clicks "Pay" → `POST /api/v1/orders` with `Idempotency-Key`. +2. Entry point: `OrdersController.create`. +3. Modules: `OrdersService`, `InventoryService.reserve`, `PaymentsService.createIntent`, `StripeAdapter`. +4. Output: `{ order, client_secret }` — frontend confirms with Stripe.js. +5. Evidence: Playwright `e2e/checkout.spec.ts` saves trace + screenshot + video; on staging captures Datadog APM trace ID. + +### Edge Cases + +- Inventory race condition during flash sale: optimistic lock fails → `InventoryService.reserve` retries up to 3x with jitter. +- Pix QR expired (5 min): UI auto-renews if window still open; if closed, customer regenerates from order detail. +- Chargeback after fulfillment: order moves to `disputed`, fulfillment is **not** auto-reversed; ops team triages. diff --git a/docs-site/versioned_docs/version-0.7.3/concepts/skills-and-agents.md b/docs-site/versioned_docs/version-0.7.3/concepts/skills-and-agents.md new file mode 100644 index 0000000..04989a3 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/concepts/skills-and-agents.md @@ -0,0 +1,29 @@ +--- +title: Skills and Agents +description: How LLM Project Mapper turns repeated conventions into reusable operating context. +sidebar_position: 1 +--- +# Skills and Agents + +LLM Project Mapper is built around a simple idea: agents perform better when project conventions are explicit, reusable, and close to the code. + +## The three context layers + +1. **Instruction layer**: `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` explain how work should be executed. +2. **Reference layer**: `.specs/`, `docs/`, and the changelog hold durable human-readable context. +3. **Execution layer**: `.skills/`, `.agents/`, hooks, and validation scripts turn that context into repeatable agent behavior. + +## Why skills matter + +Skills are not dependencies or code generators. They are small operational manuals that an agent can load on demand when a request matches a known pattern such as E2E testing, commit formatting, or multi-agent execution. + +## Why this site exists + +The repository already contains the source docs. This site simply gives them a navigable hub with: + +- versioned docs +- full-text local search +- predictable categories for quickstart, guide, concepts, reference, and community +- GitHub Pages deployment on every push to `main` + +For the raw source files, see the repository paths referenced throughout this site. diff --git a/docs-site/versioned_docs/version-0.7.3/concepts/yool-tuple-hamt.md b/docs-site/versioned_docs/version-0.7.3/concepts/yool-tuple-hamt.md new file mode 100644 index 0000000..dcd2ed2 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/concepts/yool-tuple-hamt.md @@ -0,0 +1,63 @@ +--- +title: YOOL / tuple / HAMT +description: Capability addressing pattern, receipt flow, and MCP edge guidance. +sidebar_position: 4 +slug: /yool-tuple-hamt +--- +# YOOL / tuple / HAMT + +The YOOL / tuple / HAMT pattern is the capability-addressing model that LLM Project Mapper is standardizing for multi-agent repositories. + +## Why it exists + +- Agents need stable capability ids, not only friendly names. +- Dispatch needs explicit authority and lane routing. +- Receipts need a canonical place and schema. +- MCP should stay at the edge for snapshot and dispatch, not become the inner loop. + +## Try it + +```bash +npx @wesleysimplicio/llm-project-mapper --mcp-edge +bin/build-hamt-catalog +``` + +That flow gives you: + +- `.catalog/agents.json` as the generated HAMT catalog +- `.receipts/` as the default local receipt store +- `mcp/server.ts` and `mcp/server.py` as edge adapters when `--mcp-edge` is enabled + +## Static layout + +```json +{ + "yool_id": "agent.dev.python.v1", + "authority": "dev", + "lane": "fast", + "agent_terms": { + "cpu_quota_pct": 60, + "disk_quota_mb": 100 + } +} +``` + +## Dynamic flow + +```text +AGENTS.md + -> bin/build-hamt-catalog + -> .catalog/agents.json + -> MCP snapshot / dispatch edge + -> workers subscribe by lane + -> .receipts/ evidence +``` + +## MCP is the edge + +MCP is for read-mostly snapshots and external dispatch entrypoints. Keep tuple matching, scheduling, retries, and worker coordination outside the MCP adapter. + +## Canonical spec + +- [Root spec on GitHub](https://github.com/wesleysimplicio/llm-project-mapper/blob/main/YOOL_TUPLE_HAMT.md) +- [Vendored source in this repo](https://github.com/wesleysimplicio/llm-project-mapper/blob/main/docs/YOOL_TUPLE_HAMT.md) diff --git a/docs-site/versioned_docs/version-0.7.3/guide/_category_.json b/docs-site/versioned_docs/version-0.7.3/guide/_category_.json new file mode 100644 index 0000000..5e67b4a --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/guide/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Guide", + "position": 2, + "collapsible": false, + "collapsed": false +} diff --git a/docs-site/versioned_docs/version-0.7.3/guide/private-overlay.md b/docs-site/versioned_docs/version-0.7.3/guide/private-overlay.md new file mode 100644 index 0000000..cf4b4ff --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/guide/private-overlay.md @@ -0,0 +1,283 @@ +--- +title: Private Overlay Install +description: Install the starter into an existing host project without polluting its git history. +sidebar_position: 1 +--- +> Step-by-step guide to using LLM Project Mapper as a **private overlay** on top of an existing project (front-end Angular/React/Next, .NET API, monorepo, etc.). The starter files live **on the dev's disk** but **outside the host project's git** — each dev installs their own, the main repo is not polluted. +> +> If you want to run the starter as a standalone repo (direct clone, no host project), see [README.md](/quickstart/get-going). This guide is for **overlay**. + +![Animated terminal screencast showing cd into host-project, npx llm-project-mapper, CLI prompts, and ls .specs/](/assets/overlay-install.svg) + +> 🇧🇷 Portuguese version: [INSTALL.md](https://github.com/wesleysimplicio/llm-project-mapper/blob/main/INSTALL.md). + +--- + +## TL;DR — 4 steps + +1. **Download** llm-project-mapper into a temp directory. +2. **Copy** the contents (excluding `.git`) into the host project's root. +3. **Remove** the temp directory and any starter git traces. +4. **Add** the starter paths to the host's `.gitignore`. + +Then run `bootstrap.sh` / `bootstrap.ps1` inside the host to fill placeholders and generate `.starter-meta.json`. + +--- + +## Prerequisites + +| Requirement | Purpose | +|---|---| +| Git | clone the starter | +| Bash 4+ or PowerShell 5.1+ | run the bootstrap | +| Node.js >= 16.7 (optional) | use `npx @wesleysimplicio/llm-project-mapper` instead of clone | + +--- + +## Step 1 — Download the starter + +### macOS / Linux / Git Bash / WSL + +```bash +cd /tmp +git clone --depth=1 https://github.com/wesleysimplicio/llm-project-mapper.git llm-project-mapper-src +``` + +### Windows PowerShell + +```powershell +cd $env:TEMP +git clone --depth=1 https://github.com/wesleysimplicio/llm-project-mapper.git llm-project-mapper-src +``` + +> Alternative without clone: `npx @wesleysimplicio/llm-project-mapper` inside the host (Steps 2 and 3 happen automatically). Skip to **Step 4** afterwards. + +--- + +## Step 2 — Copy into the host project (without overwriting host files) + +Assume the host project is `~/code/my-front` (Linux/macOS) or `C:\Users\me\source\my-front` (Windows). + +> ⚠️ **Warning**: the starter ships files with common names (`README.md`, `package.json`, `playwright.config.ts`, `tests/`, `AGENTS.md`, `CLAUDE.md`, `INIT.md`, `.gitignore`). If the host already has any of these, **use `--ignore-existing` (rsync) or `/XC /XN /XO` (robocopy)** to never overwrite. The bootstrap later reads pre-existing files via `.starter-meta.json` and merges through `INIT.md`. + +### macOS / Linux / Git Bash / WSL + +```bash +cd ~/code/my-front + +# copies everything from the starter except its .git, and NEVER overwrites host files +rsync -av --ignore-existing --exclude='.git' /tmp/llm-project-mapper-src/ ./ +``` + +> If `rsync` is not installed, install it (`brew install rsync` / `sudo apt install rsync`). **Do not use `cp -R`** without overwrite protection. + +### Windows PowerShell + +Always use **double quotes** around paths (Windows may have spaces like `C:\Users\Wesley Simplicio\source`): + +```powershell +cd "C:\Users\me\source\my-front" + +# /E recursive; /XD .git excludes starter's .git; +# /XC /XN /XO skips files that already exist at destination (changed/newer/older). +robocopy "$env:TEMP\llm-project-mapper-src" "." /E /XD .git /XC /XN /XO +# robocopy returns 0-7 as success; code 1 = files copied, OK. +``` + +--- + +## Step 3 — Clean up starter git traces + +Ensures the host repo does **not** become a clone of llm-project-mapper. + +> `--exclude='.git'` on `rsync` (Step 2) and `/XD .git` on `robocopy` already prevent the starter's `.git` from being copied. This step is just validation + temp dir cleanup. + +### macOS / Linux / Git Bash / WSL + +```bash +cd ~/code/my-front + +# delete the starter temp directory +rm -rf /tmp/llm-project-mapper-src + +# confirm there is NO remote pointing at the starter repo +git remote -v +# if something like 'origin → wesleysimplicio/llm-project-mapper' appears, +# the starter's .git was copied by mistake. +# DO NOT blindly run rm -rf .git — you might be deleting the HOST's git. +# Instead: +# 1. Check the host has its own commits: git log --oneline -5 +# 2. If the log is only the starter's, remove the remote: git remote remove origin +# 3. If host commits are interleaved, ask for manual help. +``` + +### Windows PowerShell + +```powershell +cd "C:\Users\me\source\my-front" + +Remove-Item -Recurse -Force "$env:TEMP\llm-project-mapper-src" + +# check remotes +git remote -v +# same principle: if it points at the starter, investigate before deleting anything. +``` + +--- + +## Step 4 — Optional `.gitignore` + +Do not hide starter files when the team needs to share LLM context. If you use +the recommended block, it should cover only local state/cache/build output, not +`.agents/`, `.skills/`, `.specs/`, `AGENTS.md`, or `.starter-meta.json`: + +```gitignore +# === LLM Project Mapper (auto-managed) — do not remove this header === +.codex/local +.codex/history +.claude/sessions +.claude/cache +.claude/settings.local.json +``` + +`--update` leaves `.gitignore` untouched by default. Use +`--append-gitignore yes` only when you want to refresh this local-only block. + +### Collision behavior + +Because **Step 2 uses `--ignore-existing`**, no host file gets overwritten by the copy. Per-file behavior: + +| Starter file | If host already has it | Result | +|---|---|---| +| `README.md` | yes | starter does NOT copy; host stays as-is | +| `package.json` | yes | starter does NOT copy; host stays as-is | +| `playwright.config.ts` | yes | starter does NOT copy | +| `tests/` | yes | starter does NOT merge individual existing files | +| `AGENTS.md` / `CLAUDE.md` / `INIT.md` | yes | starter does NOT copy. Bootstrap registers in `.starter-meta.json -> existing_instruction_files`; `INIT.md` reads and **merges** preserving host content | +| `.gitignore` | yes | starter does NOT overwrite. Bootstrap only **appends** at the end with a marker header (only if you answer `yes` at the prompt) | +| `.github/workflows/` | yes | starter does NOT overwrite existing workflows; only adds `dod.yml` if there is no name clash | + +> You will never have "two `package.json` files" — `rsync --ignore-existing` / `robocopy /XC /XN /XO` skip files that already exist. + +--- + +## Step 5 — Run bootstrap inside the host + +Replaces placeholders (``, ``) with real values detected from the host and generates `.starter-meta.json`. + +### macOS / Linux / Git Bash / WSL + +```bash +cd ~/code/my-front +chmod +x ./bootstrap.sh +./bootstrap.sh +``` + +### Windows PowerShell + +```powershell +cd "C:\Users\me\source\my-front" + +# PowerShell 7+ +pwsh -File .\bootstrap.ps1 + +# PowerShell 5.1 (Windows 10/11) +powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 +``` + +> Windows does not need `chmod` — PowerShell does not use an executable bit. Just invoke the `.ps1` directly. + +### Non-interactive (CI / script) + +```bash +./bootstrap.sh --yes --cli skip --append-gitignore no +``` + +> In overlay mode with `.gitignore` already containing the starter block, answer **no** when the bootstrap asks whether to append. Starter files are already ignored by your block — the bootstrap's block (which targets standalone use) is not needed. + +--- + +## Step 6 — Confirm the host's git is clean + +```bash +git status +``` + +Expected: no starter file appears as untracked/modified. If any appears, adjust `.gitignore` to cover it. + +--- + +## Updating the starter later + +When a new version of llm-project-mapper ships: + +```bash +# fetch the new version +cd /tmp +rm -rf llm-project-mapper-src +git clone --depth=1 https://github.com/wesleysimplicio/llm-project-mapper.git llm-project-mapper-src + +# repeat Step 2 — rsync keeps your specifics +cd ~/code/my-front +rsync -av --exclude='.git' --exclude='.specs/product' --exclude='.specs/architecture' --exclude='.specs/sprints' /tmp/llm-project-mapper-src/ ./ +``` + +The `--exclude`s preserve content **you** wrote in `.specs/` (vision, ADRs, sprints). Adapt if you customized other folders. + +--- + +## Uninstall the starter (overlay) + +```bash +cd ~/code/my-front + +# safe files (no host collisions) +rm -rf .agents .skills .specs .claude .codex bin +rm -f _BOOTSTRAP.md INSTALL.md INSTALL.en.md .starter-meta.json +rm -f bootstrap.sh bootstrap.ps1 +rm -rf .github/copilot presentation video +rm -f .github/copilot-instructions.md .github/workflows/dod.yml + +# starter files ONLY if you confirmed they are NOT host files +# (same list commented out in .gitignore — verify first) +# rm -f AGENTS.md CLAUDE.md INIT.md INIT.en.md README.pt-BR.md +# rm -f playwright.config.ts +# rm -rf tests/ presentation/ video/ + +# remove the "LLM Project Mapper (private overlay)" block from .gitignore manually +``` + +No `git rm` involved — those files were gitignored and never committed. + +--- + +## When NOT to use private overlay + +If your **entire team** is going to use the agents and you want skills/specs/agents shared: + +- Do not gitignore the starter files. +- Commit `.agents/`, `.skills/`, `.specs/`, `AGENTS.md`, `CLAUDE.md`, `INIT.md`, `.github/copilot*` in the host repo. +- Keep `.claude/sessions`, `.claude/cache`, `.claude/settings.local.json`, `.codex/local`, `.codex/history` in `.gitignore` (per-dev local state, not shared). + +The recommended block for that case (shared mode) is what `bootstrap.sh --append-gitignore yes` already adds — just that, without the "private overlay" block above. + +--- + +## Quick decision + +| Scenario | Mode | +|---|---| +| I am the only dev using agents on this project | **Private overlay** (this guide) | +| I want to test before committing for the team | **Private overlay** first | +| Whole team will work with agents | **Shared** (commit in host repo) | +| Brand-new project, agents from day 1 | **Standalone** — clone llm-project-mapper directly, no overlay | + +--- + +## Next steps + +1. Verify `git status` is clean on the host. +2. Open your favorite agent CLI/IDE inside the host folder. +3. Ask the agent to read `INIT.md` (or `INIT.en.md`), or run the handoff the bootstrap configured. +4. The agent will infer VISION/DOMAIN/PERSONAS from the host's code and write to `.specs/`. +5. The first technical task goes through the mandatory loop in `AGENTS.md`. diff --git a/docs-site/versioned_docs/version-0.7.3/intro.md b/docs-site/versioned_docs/version-0.7.3/intro.md new file mode 100644 index 0000000..5cb766e --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/intro.md @@ -0,0 +1,34 @@ +--- +title: Docs Home +description: The documentation hub for LLM Project Mapper. +slug: / +--- +# LLM Project Mapper Docs + +![LLM Project Mapper hero](/assets/llm-project-mapper-hero.png) + +LLM Project Mapper is an AI-friendly project scaffold that turns scattered engineering context into a stable operating model for coding agents and human reviewers. + +:::tip What this site is +This docs site is a curated view over the repo's real documentation. The source of truth stays in the repository root, and `scripts/sync-docs-site.mjs` regenerates the Docusaurus docs from those markdown files. +::: + +## Start here + +- **Quickstart**: install the starter in seconds and choose the right bootstrap path. +- **Guide**: use the private overlay workflow on top of an existing host project. +- **Concepts**: understand the architecture and domain map conventions the starter ships. +- **YOOL / tuple / HAMT**: inspect the capability-addressing pattern used by the scaffold. +- **Reference**: inspect CLI flags, the init handoff contract, and the SessionStart hook behavior. +- **Community**: contribute improvements and add your real-world showcase. + +## Site map + +| Area | What it covers | +| --- | --- | +| [Quickstart](/quickstart/get-going) | Fast install path, prerequisites, and starter overview | +| [Guide](/guide/private-overlay) | Private overlay installation on an existing repo | +| [Concepts](/concepts/skills-and-agents) | How the starter organizes skills, agents, and shared context | +| [YOOL / tuple / HAMT](/yool-tuple-hamt) | Capability addressing, receipts, and MCP edge guidance | +| [Reference](/reference/init-handoff) | Bootstrap contract, CLI flags, hooks, and generated docs | +| [Community](/community/showcase) | Showcase entries and contribution workflow | diff --git a/docs-site/versioned_docs/version-0.7.3/quickstart/_category_.json b/docs-site/versioned_docs/version-0.7.3/quickstart/_category_.json new file mode 100644 index 0000000..d3e41d2 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/quickstart/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Quickstart", + "position": 1, + "collapsible": false, + "collapsed": false +} diff --git a/docs-site/versioned_docs/version-0.7.3/quickstart/get-going.md b/docs-site/versioned_docs/version-0.7.3/quickstart/get-going.md new file mode 100644 index 0000000..be13a2f --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/quickstart/get-going.md @@ -0,0 +1,19 @@ +--- +title: Get Going in 60 Seconds +description: Overview, prerequisites, and install paths from the main README. +sidebar_position: 1 +--- +## TL;DR — get going in 60 seconds + +Pick **one** of the install paths below and run it inside your project folder. The bootstrap now starts an automatic local mapping pass immediately; `INIT.md` becomes an optional refinement step for a stronger agent. + +| OS | Recommended one-liner | +|---|---| +| **macOS** | `npx @wesleysimplicio/llm-project-mapper` | +| **Linux** | `npx @wesleysimplicio/llm-project-mapper` | +| **Windows (PowerShell)** | `npx @wesleysimplicio/llm-project-mapper` | +| **Windows (cmd.exe)** | `npx @wesleysimplicio/llm-project-mapper` | + +Same command everywhere. No bash dependency, no clone, no global install. + +--- diff --git a/docs-site/versioned_docs/version-0.7.3/reference/_category_.json b/docs-site/versioned_docs/version-0.7.3/reference/_category_.json new file mode 100644 index 0000000..c97d195 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/reference/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Reference", + "position": 4, + "collapsible": false, + "collapsed": false +} diff --git a/docs-site/versioned_docs/version-0.7.3/reference/cli-flags.md b/docs-site/versioned_docs/version-0.7.3/reference/cli-flags.md new file mode 100644 index 0000000..0b3b4d6 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/reference/cli-flags.md @@ -0,0 +1,37 @@ +--- +title: CLI Flags +description: CLI flags and update mode behavior from the main README. +sidebar_position: 1 +--- +#### Full flag list + +| Flag | Purpose | +|---|---| +| `-y, --yes` | Non-interactive (defaults: no `.gitignore` append, skip CLI handoff) | +| `-f, --force` | Overwrite starter template files. **Never** touches user instruction files (`AGENTS.md`, `CLAUDE.md`, `INIT.md`, `.github/copilot-instructions.md`, `.gitignore`) | +| `--update` | Safe update mode for an existing overlay: force starter files, leave `.gitignore` untouched, skip handoff | +| `--dry-run` | Print actions without writing | +| `--cli ` | Pick CLI for `INIT.md` handoff: `claude`, `codex`, `copilot`, `cursor`, `deepseek`, `kimi`, `minimax`, `glm`, `hermes`, `openclaw`, `aider`, `other`, `skip` | +| `--append-gitignore ` | Append recommended ignores to `.gitignore` | +| `--skip-meta` | Do not write `.starter-meta.json` | +| `--silent` | Minimal output | +| `-v, --version` | Print version | +| `-h, --help` | Show help | + +#### Python mapper flags + +| Flag | Purpose | +|---|---| +| `index ` | Scriptable mapper refresh. Returns `0` when updated, already fresh, or locked/skipped; returns `1` on failure | +| `docs ` | Render `.simplicio/docs/*.md` from the architecture inventory | +| `export-docs --target

` | Copy rendered Markdown docs to a local docs/wiki target | +| `--docs` | Render Markdown docs after `map` or `index` | +| `--no-docs` | Keep `map` / `index` JSON-only | +| `--docs-only` | Render Markdown docs without emitting the index JSON payload | +| `--json-only` | Compatibility alias for JSON-only refresh workflows | +| `--changed-only` | Compatibility alias for incremental refresh workflows | +| `--background` | Start a detached index refresh and log to `.simplicio/background-index.log` | +| `--json` | Emit stable JSON contracts such as `simplicio.mapper-index/v1` | +| `--update` | Compatibility alias for index refresh workflows | +| `--verbose` | Show index refresh progress | +| `--out ` | Artifact directory, defaulting to `.simplicio` | diff --git a/docs-site/versioned_docs/version-0.7.3/reference/init-handoff.md b/docs-site/versioned_docs/version-0.7.3/reference/init-handoff.md new file mode 100644 index 0000000..4d823d9 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/reference/init-handoff.md @@ -0,0 +1,197 @@ +--- +title: INIT Handoff Contract +description: The initialization contract that agents follow after bootstrap. +sidebar_position: 2 +--- +> You are the **init agent**. The human has just run `./bootstrap.sh` (or `pwsh ./bootstrap.ps1`, or `npx @wesleysimplicio/llm-project-mapper`). +> Your job: complete the setup by **reading the real project**, **asking only what is missing** and **merging** what already exists — never destroying the human's content. +> +> CLIs with a native agent loop: **Claude Code**, **Codex CLI**, **Cursor Agent**, **Hermes Agent**, **OpenClaw**, **Aider** (Deepseek/Kimi/MiniMax/GLM via `--model`). +> No native loop (paste prompt manually): **GitHub Copilot CLI**. + +> 🇧🇷 Portuguese version: [INIT.md](https://github.com/wesleysimplicio/llm-project-mapper/blob/main/INIT.md). + +--- + +## Rule zero — destroy nothing + +Before any Write/Edit, read `.starter-meta.json` at the repo root. It is the contract between `bootstrap` and you. + +```jsonc +{ + "product_name": "...", + "team": "...", + "domain": "...", + "stack": "...", + "bootstrapped_at": "2026-05-08T19:45:00Z", + "starter_version": "0.2.0", + "existing_instruction_files": [".github/copilot-instructions.md"], + "init_must_ask": ["team", "domain", "vision_oneliner", "primary_personas"], + "init_must_merge": [".github/copilot-instructions.md"], + "read_only_globs": ["**/*.razor", "**/*.cs", "package.json", "..."] +} +``` + +Three non-negotiable rules derived from that file: + +1. **`read_only_globs`** — No file matching these globs may appear in `git diff`. You read them, you do **not** write. If you need information from one, paraphrase it into `.specs/`; never touch the original. +2. **`init_must_merge`** — For each path: **read** the current content, **preserve the essence**, **merge** with our standard structure. Never rewrite from scratch. +3. **`init_must_ask`** — Ask the human **only** for these fields. Everything else (`product_name`, `stack`) was auto-detected. + +--- + +## Where you may write (whitelist) + +Only these paths are "starter-managed". Anything outside is the human's territory — do not touch. + +``` +.specs/** .agents/** .skills/** +.claude/** .codex/** +.github/copilot-instructions.md +.github/copilot/** +.github/PULL_REQUEST_TEMPLATE.md +.github/ISSUE_TEMPLATE/** +.github/workflows/ci.yml +.github/workflows/dod.yml +AGENTS.md CLAUDE.md README.md README.pt-BR.md +SIMPLICIO_INTEGRATION.md +playwright.config.ts (only if missing or still our template) +``` + +Path outside this whitelist **and** not part of the original template = do not write. + +--- + +## Flow (5 phases — parallelize everything you can) + +### Phase 1 — Read `.starter-meta.json` and ask only what is missing + +1. `Read .starter-meta.json`. If missing, abort and tell the human to run `./bootstrap.sh` first. +2. For each item in `init_must_ask`, ask the human **in a single message** (not one by one): + - **`team`** — Which team owns this? (suggestion: ``) + - **`domain`** — Business domain in 1-3 words? (suggestion: ``) + - **`vision_oneliner`** — In one sentence, what problem does this product solve and for whom? + - **`primary_personas`** — Who uses it? (2-4 roles, e.g. `operations admin`, `end customer`, `financial analyst`) +3. Persist answers by updating `.starter-meta.json` (add/overwrite `team`, `domain`, `vision_oneliner`, `primary_personas`). +4. If the human leaves something unanswered, mark `**TODO: human to fill**` in the doc and move on. + +### Phase 2 — Inspection (1 dedicated agent, parallel with the start of phase 3) + +Spawn `@inspector` (sub-agent `Explore` or `general-purpose`): + +- Read `.starter-meta.json` to know the stack. +- Map top-level folders (`ls -la`, `find . -maxdepth 2 -type d`). +- Read the original `README.md` (if it exists and is not our template) — extract description, badges, commands. **Do not modify.** +- Detect entities by stack convention: + - **Node/TS** → `**/models/**`, `**/entities/**`, `**/types/**`, `**/schemas/**`, `**/*.dto.ts` + - **.NET** → `**/Models/**`, `**/Entities/**`, `**/DTOs/**`, `**/*.cs` with `[Table]`/`[Key]` + - **Python** → `**/models.py`, `**/schemas.py`, `**/entities/**`, `BaseModel`/`SQLAlchemy` classes + - **Go** → `**/models/**`, structs with `db:` or `json:` tags + - **Rust** → `**/models.rs`, structs with `#[derive(Serialize)]` + - **Flutter** → `lib/models/**`, `freezed`/`json_serializable` classes + - **PHP/Laravel** → `app/Models/**` + - **Ruby** → `app/models/**` +- Detect external integrations: imports of `axios`/`fetch`/`HttpClient`/`requests`/`reqwest`, env vars (`*_URL`, `*_KEY`, `*_TOKEN`), connection strings. +- Detect real scripts/commands: `package.json` `scripts`, `Makefile`, `composer.json` `scripts`, `pyproject.toml` `[tool.poetry.scripts]`, `*.csproj` targets. +- TODO/FIXME/HACK in production code (exclude `node_modules`/`vendor`/`dist`/`build`). +- Open issues via `gh issue list --limit 50` if `gh` is authenticated. +- Validate `.simplicio/project-map.json` and `.simplicio/precedent-index.json`; if missing, run `npx @wesleysimplicio/llm-project-mapper map --incremental`. + +**Inspector output** — markdown report saved at `.specs/journal/inspection-.md` with sections: +`Real stack`, `Folder structure`, `Detected entities`, `Useful commands`, `Integrations`, `TODOs found`, `Open issues`. + +### Phase 3 — Parallel fill (6 agents in a single message) + +After phase 1 (answers received) and with phase 2 already running, dispatch **in parallel** (one message, multiple `Agent` calls): + +| Agent | Output | Input | +|---|---|---| +| `@vision-writer` | `.specs/product/VISION.md` | `vision_oneliner` + original README + description from `package.json`/`*.csproj`/`pyproject.toml` | +| `@domain-mapper` | `.specs/product/DOMAIN.md` (Mermaid `erDiagram`) | entities detected by inspector | +| `@personas-writer` | `.specs/product/PERSONAS.md` | `primary_personas` + roles/permissions detected in code | +| `@design-mapper` | `.specs/architecture/DESIGN.md` (Mermaid with real boundaries) | folder structure + integrations + frameworks | +| `@patterns-extractor` | `.specs/architecture/PATTERNS.md` | naming/structure/conventions **actually observed** in code (do not invent) | +| `@backlog-collector` | `.specs/sprints/BACKLOG.md` | TODOs + open issues from `gh` | + +### Phase 4 — Merge pre-existing files (sequential — uses phase 3 context) + +For **each path** in `init_must_merge`: + +1. `Read` the human's existing file. +2. Identify the **essence**: important commands, project-specific rules, internal links, glossary, contacts, compliance constraints. +3. Compose a new file with the starter's **template** structure (Stack / Commands / Workflow / DoD / Patterns / Where to find context / Forbidden / Skills / Custom agents) **plus** a `## Preserved content from ` section at the end with the human's essence. +4. `Write` to the same path. The resulting diff must be **additive enrichment**, never removing what the human wrote. +5. **Mirroring is mandatory:** if you edited `AGENTS.md`, replicate the same change in `CLAUDE.md` and `.github/copilot-instructions.md`. The three stay aligned (or symlink: `ln -sf AGENTS.md CLAUDE.md`). + +### Phase 5 — Update real commands and validate + +1. **`@instruction-updater`** — updates `AGENTS.md`/`CLAUDE.md`/`.github/copilot-instructions.md`: + - Replace the `## Important commands` section with **real** commands extracted by the inspector (no placeholders). + - Add links to docs filled in `.specs/`. + - Add `## Available skills/agents` listing what exists in `.skills/` and `.agents/`. + - Confirm `.starter-meta.json.simplicio` points to `project-map.json`, `precedent-index.json`, and `SIMPLICIO_INTEGRATION.md`. + +2. **DoD checks**: + - Every tree file exists (`AGENTS.md`, `CLAUDE.md`, `.specs/{product,architecture,workflow,sprints}/...`). + - No ``/``/``/`` placeholders left in starter-managed paths. + - Mermaid blocks are syntactically valid (no accents in IDs; labels with spaces wrapped in quotes). + - No meaningful doc below 30 useful lines. + - **Critical check:** `git status` must **not** list any file matching `read_only_globs`. If it does, something escaped — revert with `git checkout -- `. + +3. **Report to the human**: + - Files filled (list). + - Top 5 detected entities. + - Commands identified. + - What remained as **TODO: human to fill**. + - Suggested next action (create `sprint-01/SPRINT.md`, open the first ADR, configure branch protection, etc.). + +--- + +## Optional cleanup + +Ask the human: + +> "Delete `_BOOTSTRAP.md`, `INIT.md`, `bootstrap.sh`, `bootstrap.ps1` now? (y/N)" + +If `y`: + +```bash +rm _BOOTSTRAP.md INIT.md bootstrap.sh bootstrap.ps1 +git add -A +git commit -m "chore: remove starter bootstrap files after init" +``` + +Keep `.starter-meta.json` (future reference). + +--- + +## Execution rules + +- **Language**: generated content in **English**. Code (vars/functions/classes), commits, identifiers: **English**. +- **Never invent** — if the code cannot give you certain info, mark **`TODO: human to fill`** explicitly. +- **Concrete > generic** — use real names (entities, routes, project commands), not placeholders. +- **No emojis** in source code. +- **Valid Mermaid** — IDs without accents; labels with spaces in quotes (`["Order Service"]`). +- **Aggressive parallelism** — any independent work goes in a single message with multiple `Agent` calls. +- **Read-only is law** — any file matching `read_only_globs` is untouchable. If it appears in `git diff`, revert. +- **Merging is the rule for `init_must_merge`** — never rewrite from scratch, always compose on top. +- **No new dependencies** without asking. + +--- + +## Final agent checklist + +- [ ] `.starter-meta.json` read and updated with the human's answers. +- [ ] `init_must_ask` asked **once**, in a single message. +- [ ] Inspector ran and produced a report with real entities/commands/integrations. +- [ ] `.simplicio/project-map.json` and `.simplicio/precedent-index.json` exist and were updated after inspection. +- [ ] 6 docs in `.specs/` filled with real info (not placeholders). +- [ ] `init_must_merge` merged with the essence preserved. +- [ ] `AGENTS.md` ↔ `CLAUDE.md` ↔ `.github/copilot-instructions.md` aligned. +- [ ] `git status` does not list any file from `read_only_globs`. +- [ ] No ``/``/``/`` placeholders left in starter paths. +- [ ] Summary delivered to the human: files, entities, commands, TODOs, next action. + +--- + +**INIT.md is disposable after a single run. No config lives here — config lives in `.specs/`.** diff --git a/docs-site/versioned_docs/version-0.7.3/reference/session-start-hook.md b/docs-site/versioned_docs/version-0.7.3/reference/session-start-hook.md new file mode 100644 index 0000000..4b6e4c9 --- /dev/null +++ b/docs-site/versioned_docs/version-0.7.3/reference/session-start-hook.md @@ -0,0 +1,78 @@ +--- +title: SessionStart Hook +description: How the always-on skills hook works and how to debug or disable it. +sidebar_position: 3 +--- +> Operational doc for the always-on skills SessionStart hook shipped with the LLM Project Mapper starter. +> File: `.claude/hooks/session-start-skills.sh` (Bash) — wired in `.claude/settings.json` under `hooks.SessionStart`. + +## What it does + +Every time Claude Code starts (or resumes) a session inside a directory that contains `.claude/`, the hook runs and writes a small block to `stdout`. Claude Code captures that block and prepends it to the conversation as a ``. The end result: three skills are **already loaded** for the agent without any explicit user request. + +The three injected skills: + +| Skill | Level | Effect | +|---|---|---| +| `caveman` | `full` | Terse output mode. Drops articles/filler. Preserves code, commits, PRs and canonical docs in normal prose. | +| `ralph-loop` | always-on | Wraps every technical task in `read → plan → execute → lint → unit → e2e → fix → repeat` until DoD turns green. Dual exit gate (indicators + `EXIT_SIGNAL: true`). | +| `everything-claude-code` | always-on | Forces maximum parallelism on agent invocations after edits. Stack-specific reviewers + `security-reviewer` are mandatory. | + +## When the hook fires + +| Trigger | Fires? | +|---|---| +| `claude` invoked fresh in a directory with `.claude/settings.json` | yes (event `SessionStart`) | +| `claude /resume ` | yes (event `SessionResume`) | +| Sub-agent invoked inside an existing session | no — the parent's reminder already contains the block | +| Different IDE/CLI (Codex, Cursor, Copilot) | no — they do not honor Claude Code hooks; equivalent context lives in `AGENTS.md` | + +## How to debug + +Run the hook manually: + +```bash +bash .claude/hooks/session-start-skills.sh +``` + +Expected output: the same block you see at the top of a fresh `claude` session. If you see nothing, the hook is not executable — re-run `chmod +x .claude/hooks/session-start-skills.sh`. + +To see whether Claude Code is actually invoking the hook, set `CLAUDE_LOG=debug` and look for the `hook_executed` event in `~/.claude/logs/`. + +## How to customize + +The hook is plain Bash. To add a new always-on skill, edit the heredoc inside `session-start-skills.sh`: + +```bash +4. `your-skill` — short description. Detalhe: .skills/your-skill/SKILL.md +``` + +Do not invent skills that do not exist on disk — the message becomes a lie and the agent will eventually call out the mismatch. Always pair a new line in the hook with a real `.skills//SKILL.md`. + +## How to disable temporarily + +Three escape hatches, increasing in scope: + +1. **Per-prompt** — say `stop caveman` or `normal mode` in chat. Disables the terse style; the other skills remain. +2. **Per-session** — start Claude Code with `SKIP_CLAUDE_HOOKS=1 claude` (the harness checks this env var before running any hook). +3. **Per-repo** — remove the entry from `.claude/settings.json`: + + ```jsonc + { + "hooks": { + "SessionStart": [] + } + } + ``` + +To make the change reversible across teammates, gate the hook on a `STARTER_SKILLS_OFF` env var instead of deleting the file — then anyone can re-enable with `unset STARTER_SKILLS_OFF`. + +## Why a hook instead of `AGENTS.md` + +`AGENTS.md` is read by the agent **on demand**. The hook output is injected **automatically** by the harness, before the agent reads anything. That guarantees the three skills are active from token 1, even on quick "ask me something" sessions where the agent might otherwise skip reading the master instruction file. + +## Related files + +- `.claude/settings.json` — declares `hooks.SessionStart`. +- `.skills/caveman/SKILL.md`, `.skills/ralph-loop/SKILL.md`, `.skills/everything-claude-code/SKILL.md` — full skill definitions. +- `bin/hook-runner.js` — shared cross-platform runner used by post-edit + pre-commit hooks (not by SessionStart, which is Bash-only). diff --git a/docs-site/versioned_sidebars/version-0.7.3-sidebars.json b/docs-site/versioned_sidebars/version-0.7.3-sidebars.json new file mode 100644 index 0000000..39332bf --- /dev/null +++ b/docs-site/versioned_sidebars/version-0.7.3-sidebars.json @@ -0,0 +1,8 @@ +{ + "docsSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs-site/versions.json b/docs-site/versions.json index 3145067..7754de3 100644 --- a/docs-site/versions.json +++ b/docs-site/versions.json @@ -1,3 +1,4 @@ [ + "0.7.3", "0.2.0" ] diff --git a/tests/unit/docs-site.test.js b/tests/unit/docs-site.test.js index 60aaf1b..74db864 100644 --- a/tests/unit/docs-site.test.js +++ b/tests/unit/docs-site.test.js @@ -13,7 +13,7 @@ function read(rel) { test('README advertises the docs site near the top', () => { const lines = read('README.md').split('\n').slice(0, 8).join('\n'); - assert.match(lines, /wesleysimplicio\.github\.io\/llm-project-mapper/); + assert.match(lines, /wesleysimplicio\.github\.io\/simplicio-mapper/); }); test('docs site config enables mermaid, local search, and root docs routing', () => {