Files

T

Jon Chery 2c08c778a9 docs(P4): Atelier skills mapping — 9 skill files + index + BA.A extension (REQ-221, REQ-222)

REQ-221: skills/ directory with 9 Atelier-derived skill files mapped to the
BA.A citizen-developer catalog: api, security, data, testing, observability,
errors, devops, infrastructure-as-code, compliance. Each names the Atelier
source path, distills first-principles to the citizen-dev-relevant subset,
links to agent-checklist triggers, maps to BA.A 5-skill catalog.

REQ-222: docs/skills.md index (9-skill table, Atelier provenance, 8 core
principles C1-C8, consumption instructions, reference-only domains, excluded
domains). PROJECT.md BA.A decision extended with the Atelier-derived skill
catalog reference.

---ci---
project: acdl
phase: 4
milestone: v1.18
status: execute
requirements:
  covered: [REQ-221, REQ-222]
  partial: []
---/ci---

2026-08-06 15:11:12 +00:00

4.6 KiB

Raw Blame History

Skills — Production-Grade Guidance for the Citizen Developer

Source of truth (v1.18, REQ-221, REQ-222). The Nova skill catalog extends the BA.A 5-skill catalog (web API, worker, scheduled job, static asset, basic observability bootstrap) with Atelier-derived production- grade engineering principles. Each skill is a markdown file under skills/ keyed to an Atelier domain path.

How the Citizen Developer's AI Agent Consumes Skills

Before completing a task, read the relevant skill file(s) that match the task's domain.
Run review/agent-checklist.md (from Atelier) before finishing — the checklist items are the gate between "the code is written" and "the task is done."
Use the Atelier MCP server (mcp/atelier/server.py, P5) for agentic validation — the atelier.validate_against_principles tool catches correctness/clarity/simplicity/observability gaps that deterministic scanners (Wiz, Checkmarx, Mend) cannot.

The 9 Skills

Skill	Atelier Source	Core Principles	BA.A Mapping
`api.md`	`domains/api/`	C1, C2, C6	web API
`security.md`	`domains/security/`	C1	cross-cutting (all 5)
`data.md`	`domains/data/`	C1, C4, C6	web API, worker, scheduled job
`testing.md`	`domains/testing/`	C1, C5	UAT (citizen-dev RACI)
`observability.md`	`domains/observability/`	C7	basic observability bootstrap
`errors.md`	`domains/errors/`	C1, C7	web API, worker, scheduled job
`devops.md`	`domains/devops/`	C5, C7, C8	scheduled job, worker
`infrastructure-as-code.md`	`domains/infrastructure-as-code/`	C1, C5, C8	static asset
`compliance.md`	`domains/compliance/`	C1, C5	cross-cutting (all 5)

Atelier Provenance

The skills are derived from Atelier — a first-principles docs-as-code engineering framework with 8 core principles (C1–C8) and 19 domains, each with 10 derived P-rules. The skills distill the citizen-developer-relevant subset of each domain's first-principles, link to the agent-checklist triggers, and map to the existing BA.A catalog.

Atelier is vendored under mcp/atelier/vendor/ (pinned tag, D-136) for audit reproducibility — an agentic validation result is replayable against the exact principles that produced it.

The 8 Core Principles (from Atelier)

#	Principle	One-line
C1	Correctness	The system does what it is supposed to do, and nothing else.
C2	Clarity	The intent of the code is obvious to its reader.
C3	Simplicity	The solution is as simple as possible, and no simpler.
C4	Locality	Decisions and their consequences live near each other.
C5	Reversibility	Every decision can be undone, and the cost of undoing is known.
C6	Composability	Parts combine into wholes, and the parts are reusable.
C7	Observability	The system's behavior is visible to those who must understand it.
C8	Economy	The system uses no more resources than the task requires.

Precedence: C1 > C2 > C3 > C4 > C5 > C6 > C7 > C8. Correctness is never sacrificed.

Reference-Only Domains (cited inside skills, not elevated to skill files)

These 4 Atelier domains are relevant to a citizen developer but are cited inside the 9 skills above rather than getting their own skill file:

Performance (domains/performance/) — cited in observability.md + devops.md (bounded operations, timeouts, N+1)
Documentation (domains/documentation/) — the runbook requirement (W3.E prod mandatory) is the documentation skill in practice
Concurrency (domains/concurrency/) — cited in errors.md + devops.md (bounded queues, cancellation, timeout)
AI/ML (domains/ai-ml/) — scope: engineering discipline (data versioning, evaluation, serving, drift), not algorithm design

Excluded Domains (not relevant to Nova citizen developer)

6 Atelier domains are excluded from the Nova skill catalog (not relevant to a citizen developer building on Nova's infrastructure platform):

UI/UX — Nova has no frontend (frontend-engineer deactivated, PERSONAS.md)
Kubernetes — Nova is AWS-only this milestone (NORTH_STAR Non-Goal #7)
GitOps + Operators — future roadmap (no GitOps reconciler today)
Edge — not in scope (Nova is cloud, not edge)
Messaging — not in scope (Nova deploys infra, not message brokers)
i18n — application-level concern, not infrastructure

4.6 KiB Raw Blame History Unescape Escape