docs(scaffold): fill the repo's own AGENTS.md / CLAUDE.md / .specs placeholders (closes #99)#111
Merged
Merged
Conversation
…pecs/product Closes #99. This repo is the canonical scaffold whose whole purpose is to remove placeholders from host projects, yet its own AGENTS.md and CLAUDE.md still carried `<STACK>` lines and the host-only placeholder list (`<APP_NAME>`, `<FRONTEND_URL>`, `<BACKEND_URL>`, `<DATABASE_REQUIREMENT>`, `<AUTH_FLOW>`, `<EVIDENCE_COMMAND>`), and the commands block still pointed at generic `npm run dev` / `npm run build` that do not exist here. The `.specs/product/` files were also template prose. Fill them with the repo's real identity: - AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md now declare the real stack (Python 3.10+ canonical with `orjson` + `diskcache`, Node CLI mirror at `bin/cli.js`, optional Rust/PyO3 acceleration, Playwright E2E), list the actual project-identity slots (CLI tool, no UI, PyPI-only since 0.7.x), and document the commands that actually run here (`python -m unittest discover`, `ruff check`, `node scripts/check-version-sync.js`, `(cd rust && maturin develop)`). - `.specs/product/VISION.md` describes the real product thesis: deterministic project context as a compilable artifact, not a prompt. - `.specs/product/DOMAIN.md` lists the real entities (ProjectFile, Precedent, Module/Layer, Symbol, CallEdge, Endpoint, Screen, IndexState, Receipt), the seven critical rules (schema is contract, determinism, idempotency, no-LLM-on-the-critical-path, generic normalization, lightweight deps, cross-runtime parity) and the documented edge cases. - `.specs/product/PERSONAS.md` captures the five real consumers (P1 SendSprint orchestrator, P2 simplicio-dev-cli, P3 human maintainer, P4 CI / DoD, P5 release maintainer) with the commands each calls and the guarantees they need. No code changes. CLAUDE.md and .github/copilot-instructions.md stay aligned with AGENTS.md as the repo's own contributing rule requires. https://claude.ai/code/session_01JdmemqddwFnvbceWyuDE8m
Contributor
There was a problem hiding this comment.
Pull request overview
Este PR fecha a #99 ao “dogfoodar” o próprio scaffold: substitui placeholders (ex.: <STACK>, <APP_NAME>) por contexto real do simplicio-mapper e atualiza os docs de produto em .specs/product/ para refletir tese, domínio e personas do repositório.
Changes:
- Preenche identidade/stack/comandos reais em
AGENTS.md,CLAUDE.mde.github/copilot-instructions.md. - Reescreve
.specs/product/VISION.md,DOMAIN.mdePERSONAS.mdcom conteúdo específico dosimplicio-mapper(artefatos, entidades, regras e consumidores).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
CLAUDE.md |
Alinha instruções do Claude Code com a identidade/stack/comandos reais do repo. |
AGENTS.md |
Atualiza contexto operacional + stack + comandos importantes do scaffold canônico. |
.specs/product/VISION.md |
Define problema, proposta de valor e critérios de sucesso do simplicio-mapper. |
.specs/product/DOMAIN.md |
Formaliza entidades, regras críticas e casos de borda do domínio. |
.specs/product/PERSONAS.md |
Substitui template por personas reais (orquestrador, CLI consumidor, CI, maintainer). |
.github/copilot-instructions.md |
Replica stack e comandos reais para o Copilot/Agent Mode. |
| - Linter/formatter: `<STACK>` (sugestão: ESLint + Prettier, Ruff, dotnet format) | ||
| - CI/CD: GitHub Actions (ver `.github/workflows/`) | ||
| - Deploy: `<STACK>` (Vercel/Netlify/Docker/Azure/AWS — ver `.specs/workflow/RELEASE.md`) | ||
| - Linguagem principal: **Python 3.10+** (canonical PyPI package `simplicio-mapper`); um espelho Node 18+ vive em `bin/cli.js` + `bin/mapper-artifacts.js` mantido em paridade. |
Comment on lines
+96
to
+98
| ruff check simplicio_mapper tests/python # Python lint | ||
| node scripts/check-version-sync.js # versões alinhadas (package/pyproject/__init__) | ||
| python -m unittest discover -s tests/python # Python unit |
Comment on lines
27
to
28
| Key placeholders to replace in real projects: | ||
|
|
| - Linter/formatter: `<STACK>` (sugestão: ESLint + Prettier, Ruff, dotnet format) | ||
| - CI/CD: GitHub Actions (ver `.github/workflows/`) | ||
| - Deploy: `<STACK>` (Vercel/Netlify/Docker/Azure/AWS — ver `.specs/workflow/RELEASE.md`) | ||
| - Linguagem principal: **Python 3.10+** (canonical PyPI package `simplicio-mapper`); um espelho Node 18+ vive em `bin/cli.js` + `bin/mapper-artifacts.js` mantido em paridade. |
Comment on lines
+99
to
+103
| npm run lint # JS + shell lint (scripts/lint.js) | ||
| ruff check simplicio_mapper tests/python # Python lint | ||
| node scripts/check-version-sync.js # versões alinhadas (package/pyproject/__init__) | ||
| python -m unittest discover -s tests/python # Python unit | ||
| node --test tests/unit # Node unit |
Comment on lines
+47
to
+49
| 3. **Idempotência.** `simplicio-mapper index <path>` deve retornar exit 2 | ||
| em <200 ms quando o fingerprint não mudou. Foreground e background não | ||
| podem rodar concorrentes; lock em `.simplicio/index.lock`. |
| ``` | ||
| ## Casos de borda | ||
|
|
||
| - **Repo sem git** — `_compute_fingerprint` cai no fallback de mtimes. |
Comment on lines
+14
to
+15
| - Exit codes estáveis (0/1/2), JSON estável (`--json`), idempotência | ||
| real (<200 ms quando nada mudou). |
Comment on lines
+65
to
+67
| - Build reproduzível (`hatchling>=1.27,<1.28`). | ||
| - Versões alinhadas (`scripts/check-version-sync.js`). | ||
| - Pytest verde antes de qualquer publish. |
Comment on lines
+59
to
+60
| - **Quem** — workflows `dod.yml`, `python-ci.yml`, `scaffold-self-check.yml`, | ||
| `publish-pypi.yml`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resumo
Fecha #99. Preenche os placeholders nos arquivos canônicos do próprio scaffold (que existe pra remover placeholders de hosts).
Mudanças
AGENTS.md,CLAUDE.md,.github/copilot-instructions.md— substituem<STACK>e lista de<APP_NAME>/<FRONTEND_URL>/<BACKEND_URL>/<DATABASE_REQUIREMENT>/<AUTH_FLOW>/<EVIDENCE_COMMAND>por:python -m unittest discover,ruff check,node scripts/check-version-sync.js,(cd rust && maturin develop))..specs/product/VISION.md— tese real do produto..specs/product/DOMAIN.md— entidades reais (ProjectFile, Precedent, Module/Layer, Symbol, CallEdge, Endpoint, Screen, IndexState, Receipt) + 7 regras críticas + edge cases..specs/product/PERSONAS.md— 5 consumidores reais (SendSprint orchestrator, simplicio-dev-cli, humano de manutenção, CI/DoD, maintainer de release).Zero mudança de código.
Acceptance
<STACK>/<APP_NAME>/<PRODUCT_NAME>/<DOMAIN>emAGENTS.md,CLAUDE.md,.specs/product/(verificado por grep).npm run lint✅ 0 erros,python -m unittest discover✅ 30 pass,ruff check✅)..github/copilot-instructions.mdreflete a mesma stack/comandos.Refs #99.
https://claude.ai/code/session_01JdmemqddwFnvbceWyuDE8m
Generated by Claude Code