---
name: coding-standards
description: Create prescriptive coding standards tailored to the project's tech stack
summary: "Creates coding standards tailored to your tech stack — naming conventions, error handling patterns, import organization, AI-specific rules — and generates working linter and formatter config files."
phase: "foundation"
order: 230
dependencies: [tech-stack]
outputs: [docs/coding-standards.md]
reads: [create-prd]
conditional: null
knowledge-base: [coding-conventions]
---

## Purpose
Define the project's coding conventions with concrete, stack-specific examples
that AI agents reference during every implementation task. Covers project
structure conventions, code patterns, type safety, security, database access,
API design, logging, AI-specific pitfalls, commit message format, and a
self-review checklist.

## Inputs
- docs/tech-stack.md (required) — determines which languages, frameworks, and tools
  the standards apply to
- docs/plan.md (required) — application domain informs which patterns matter most

## Expected Outputs
- docs/coding-standards.md — prescriptive standards document with sections for
  project structure, code patterns, type safety, security, database access, API
  design, logging, AI-specific rules, commit messages, and code review checklist
- Linter/formatter config files (e.g., .eslintrc, .prettierrc, ruff.toml) created
  alongside the standards doc

## Quality Criteria
- (mvp) Every standard references the specific tech stack, not generic principles
- (deep) Includes >= 2 runnable code examples per section showing the RIGHT way for the stack
- (mvp) Commit message format documented: `type(scope): description`
  following conventional commits; if the project uses Beads task tracking,
  the task ID is appended to the subject and the PR title as a trailing tag
  (`type(scope): description (bd-<id>)`) and the PR body carries
  `Closes bd-<id>` — the canonical machine-readable mapping. Because the
  conventional `type` stays first, commit-header tooling (commitlint,
  semantic-release, changelog generators) parses these commits unchanged — the
  trailing `(bd-<id>)` is just part of the subject text, no config needed
- (mvp) AI-specific coding rules section addresses common AI mistakes (dead code,
  duplication, magic numbers, premature abstraction, unnecessary features)
- (mvp) Linter/formatter configs created and referenced from the document
- (mvp) Every standard has a corresponding linter rule, formatter rule, code review checklist item, or test pattern that enforces it (where applicable tools exist)
- (deep) Every code review checklist item is a binary yes/no question
- (mvp) Linter/formatter config files are valid (lint command runs without config errors)

## Methodology Scaling
- **deep**: Comprehensive standards with examples for every section. Stack-specific
  security patterns. Detailed error handling strategy with code samples. Full
  linter/formatter configuration with custom rules. 15-20 pages.
- **mvp**: Core naming conventions, commit format, import ordering, error handling
  approach, and AI-specific rules. Basic linter config. 3-5 pages.
- **custom:depth(1-5)**:
  - Depth 1: Core naming conventions, commit format, and import ordering. 1-2 pages.
  - Depth 2: Depth 1 + error handling approach and AI-specific rules. Basic linter config. 3-5 pages.
  - Depth 3: Add security and database access patterns. 5-8 pages.
  - Depth 4: Add API design and logging conventions. 8-12 pages.
  - Depth 5: Full suite with all sections, custom linter rules, and code review checklist. 15-20 pages.

## Mode Detection
Update mode if docs/coding-standards.md exists. In update mode: preserve naming
conventions, lint rule customizations, commit message format, and project-specific
patterns. Never change commit message format without checking git-workflow.md
and CI config for references.

## Update Mode Specifics
- **Detect prior artifact**: docs/coding-standards.md exists
- **Preserve**: naming conventions, commit message format, lint/formatter
  configurations, AI-specific coding rules, code review checklist, any
  project-specific patterns added by the team
- **Triggers for update**: tech stack changed (new language or framework
  requires new patterns), new architecture patterns need coding conventions,
  team identified recurring issues needing new rules, commit message format
  changed in docs/git-workflow.md
- **Conflict resolution**: if tech stack added a new framework, add its
  conventions as a new section rather than modifying existing sections;
  verify commit format consistency with git-workflow.md before any changes

## Adoption Mode Specifics
- **Codify from repo evidence**: the conventions the code already follows —
  read incumbent linter/formatter configs (.eslintrc*, eslint.config.*,
  biome.json, .prettierrc*, ruff.toml), sample real source files for naming,
  import, and error-handling patterns, and derive the commit-message
  convention from `git log --oneline -50` (conventional-commit adherence is
  measured, not assumed).
- **Interview only for**: whether observed inconsistencies are deliberate,
  which currently-unenforced rules the team wants tightened going forward,
  and whether new lint rules apply to new code only or to the whole repo.
- **Ingest with provenance**: translate the incumbent lint/formatter config
  into the standards document with provenance annotations; when
  `artifact_map` maps this step to an incumbent doc (e.g. CONTRIBUTING.md),
  treat that doc as the prior artifact and extend it rather than starting
  over.
- **Do not**: generate a new linter config when one exists (extend the
  incumbent); propose repo-wide reformatting sweeps; write standards the
  existing codebase violates without marking them "new code only".