ad-guidelines

name	ad-guidelines
description	Draft or update `GUIDELINES.md` at the repo root — the project's full engineering reference. Layer 1 Constitution trinity member (alongside `WORKFLOW.md` universal philosophy and `AGENTS.md` distilled rules). Covers Clean Architecture binding, SOLID application, Object Calisthenics tier (loose / moderate / strict per Bay 2008), naming conventions, error handling, complexity discipline, API rules, performance standards, build system, static analysis, quality gates, testing strategy, git workflow, documentation, and security. Scan-first — reads language toolchain, existing test/lint/format config, and existing AGENTS.md sections, pre-fills every placeholder it can verify, then asks only the genuine gaps and preference questions. Use when the user wants to draft, scaffold, audit, or update engineering guidelines / code standards / coding conventions / SOLID adoption / Object Calisthenics / testing strategy / security policy / build conventions for the project. Skill is lazy — file only exists when the project needs engineering standards.
summary	Lazy lifecycle owner of `GUIDELINES.md` (Layer 1 Constitution, full engineering reference). Twelve sections — design principles, code standards, complexity, API, performance, build, static analysis, quality gates, testing, git, documentation, security. Pre-suggested defaults from canon + scan-first detection.

<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-audit flags duplication as drift.

Skill is excluded from poc profile. Universal at solo / team / mature.

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>

Step 0 — confirm regime. Run when the user wants to scope or update project-level engineering standards: new project past poc, 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. 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.

Profile: read .claude/agentic-state.json / .agents/agentic-state.json. Profile shapes strictness defaults (mature → strict Object Calisthenics by default; solo → loose).

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 templates/guidelines.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. Default per profile (poc N/A; solo loose; team moderate; mature strict).

• 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 templates/guidelines.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.

<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 to wire the quality gates this file describes (team/mature); 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-audit. </output_contract>