ad-guidelines

<background_information> Layer 1 Constitution trinity member. Lazy lifecycle owner of `GUIDELINES.md` at the repo root. Companion to `WORKFLOW.md` (universal philosophy, kit-shipped) and `AGENTS.md` (distilled non-negotiable rules read every session). `GUIDELINES.md` is the full reference; `AGENTS.md` is the distilled summary. Each AGENTS.md section that has detail points to the corresponding GUIDELINES.md section. The two never duplicate — `ad-drift` flags duplication as drift. Codex auto-trigger on description keywords is less mature than Claude Code's. If auto-invocation does not fire when the user mentions engineering guidelines, code standards, SOLID, Object Calisthenics, testing strategy, or security policy, invoke this skill manually. </background_information> <instructions> Step 0 — confirm regime. Run when the user wants to scope or update project-level engineering standards: new project, existing rules buried in AGENTS.md, stack change, Object Calisthenics tier review. Route elsewhere when: - Scope is system structure → `ad-architecture`. - Scope is product → `ad-prd`. - Scope is vocabulary → `ad-domain`. - Scope is one binding decision → `ad-adr`. - Scope is wiring the gates → `ad-hooks`. Step 1 — codebase-first scan. From the consumer repo root, first run `node .agents/skills/ad-guidelines/scripts/project-signals.mjs AGENTS.md` and parse its JSON. `stacks` narrows the manifest reads below. Surface every `unreadable[]` entry as a scan gap, never as an absent path. If this skill loaded from a different base directory (stated at the top of the skill load), substitute it — the script lives at `scripts/project-signals.mjs` inside it. Before any preference question, detect: Language and toolchain: - `package.json` → JS/TS; read engines, scripts, deps, devDeps. - `Cargo.toml` → Rust; read edition, deps, dev-dependencies. - `pyproject.toml` / `setup.cfg` / `requirements.txt` → Python. - `CMakeLists.txt` / `CMakePresets.json` / `vcpkg.json` → C/C++. - `go.mod` → Go. - `Gemfile`, `pom.xml`, `build.gradle`, `composer.json` for other stacks. Test framework: jest/vitest/playwright/mocha configs, pytest, cargo `[dev-dependencies]`, catch2/gtest in CMake, `_test.go` files. Lint and format: `.eslintrc.*`, `.prettierrc.*`, `.rustfmt.toml`, `clippy.toml`, `.ruff.toml`, `mypy.ini`, `.clang-format`, `.clang-tidy`, `.golangci.yml`. Hooks and CI: `.husky/`, `lefthook.yml`, `.pre-commit-config.yaml`, `.githooks/`, `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`. Existing standards: - `AGENTS.md` `## Code Style` and `## Architectural Principles` — extract into GUIDELINES, replace with pointers. - `ARCHITECTURE.md` `## Source Tree` and `## Dependency Rules` — informs Clean Architecture §1.1. - `doc/adr/` — binding decisions about error handling, naming, DI — carry forward. - `CONTEXT.md` — domain vocabulary the guidelines must respect. Canonical examples: for brownfield projects, identify candidate source files that future agents should imitate. Prefer one boundary example, one core/domain function, and one test. Record paths only, never pasted snippets. If no representative code exists, omit the section until the project has examples worth copying. Project posture: derive strictness from existing code, delivery risk, and stated constraints — never from installer metadata. A disposable experiment may need only a light baseline; long-lived or safety-sensitive code needs explicit, enforceable standards. Only after the scan produces no answer does the skill ask. Asking about something the repo already states wastes the user's attention. Step 2 — pre-fill the template. Open [references/guidelines-template.md](references/guidelines-template.md). Fill detected fields before any interview: - §2.1 naming conventions table per language idiom. - §2.2 error handling per language idiom. - §2.5 canonical examples table, when representative code exists: boundary code, core/domain logic, and tests. Confirm the picks with the user before writing; do not declare weak code canonical. - §6.1 toolchain + version + source-of-truth config file. - §6.2 dependency manager from detected manifest. - §7 static-analysis tools detected. - §8 quality gates from hooks scan; mark `<not yet wired — invoke /ad-hooks>` when absent. - §9.2 unit-test framework detected. - §9.6 tag taxonomy kit defaults. - §10 git workflow kit pattern (Conventional Commits, DCO sign-off via `ad-commit`). - §11.1 document scope table kit-standard. - §12 security boundaries from scan. Sections not applicable to the project (e.g., §5 Performance Standards for a CRUD app) are omitted from the file, not left as `<TODO>`. Step 3 — interview to fill preference questions. One question at a time. Skip those already answered by the scan. 3.1 Project tradeoff statement. One sentence. Suggest from signals; user confirms or supplies. 3.2 Object Calisthenics tier. Three-choice. Reuse the existing tier when one exists. Otherwise suggest Moderate for code expected to live beyond an experiment; suggest Loose only for explicitly disposable work; choose Strict only when the project requires it. - Loose: rules 6, 7 relaxed, 1 as guideline. - Moderate: loose + rules 2, 3, 4. - Strict: all nine rules including 5, 8, 9. 3.3 Complexity caps. Confirm defaults: cognitive complexity 15, function ~50 lines, file ~200 lines, indentation ≤3. 3.4 Performance standards. Ask: perf budget? If no → skip §5 entirely. If yes → hot-path rules, baseline location, regression threshold. 3.5 Security posture. Untrusted input sources, secret-handling pattern, dependency-audit tool. 3.6 Documentation extensions. Default references WORKFLOW §2 + ad-philosophy. Ask only for project-specific extensions. 3.7 Canonical examples confirmation. If Step 1 found candidate examples, present the paths and ask whether each should be treated as canonical. Keep at most one row per pattern unless two variants are genuinely necessary. If the user cannot endorse an example, omit the section; bad exemplars are worse than no exemplars. Codex has no `AskUserQuestion` primitive — use inline numbered text for the three-tier Object Calisthenics question and other multi-choice prompts. Step 4 — AGENTS.md reciprocity. After writing `GUIDELINES.md`, offer to refresh `AGENTS.md` engineering sections as pointer stubs: ``` ## Code Standards See `GUIDELINES.md` §2 for the full reference. Non-negotiable subset: - <language naming line> - <error handling pattern line> - <no commented-out code, no orphan TODO line> ``` User confirms before the AGENTS.md rewrite. Never modify AGENTS.md silently. Step 5 — write the file. Path: `GUIDELINES.md` at repo root. Use the template at [references/guidelines-template.md](references/guidelines-template.md). Sections the user skipped do not land. Sections that were fully pre-filled land verbatim. Sections requiring preference land with the user's answer. Stop after writing; print a one-line summary. Step 6 — editing guidance for later turns. Tier change → update §3.1 checked rules; never delete the rule list (audit trail). New language → expand §2.1 table; do not rewrite existing rows. New static-analysis tool → add row to §7. Canonical example change → update §2.5 to point at the new source file; do not paste code into GUIDELINES.md. Perf budget change → update §5; never delete previous without recording rationale. Documentation extensions → append to §11.1 table. Never rewrite existing prose — append rationale paragraphs. </instructions> <output_contract> - Primary output: `GUIDELINES.md` at the repo root. - Side-effect (optional, user-confirmed): `AGENTS.md` engineering sections rewritten as pointer stubs to `GUIDELINES.md`. - No dates inside narrative prose; the file is project-state, not a decision-record artifact. Next: invoke `ad-hooks` when the project needs executable quality gates; invoke `ad-bootstrap` to refresh AGENTS.md with pointer-style sections; invoke `ad-adr` when a binding decision arises the guidelines do not yet cover; periodic drift via `ad-drift`. </output_contract>