Jon Chery
0d2cbdb423
Genericize forge-detection code: gitea→forge/generic_forge, GITEA_ACTOR→FORGE_ACTOR. Drop .gitea byte-identity test assertions (keep GitHub-side + contract conformance). Add test_no_forge_mentions.py guard test (REQ-230). Delete completed migration docs (NOVA_MIGRATION.md, NOVA_AWS_MIGRATION.md). Move NO_HUMANS_THESIS.md to .ciagent/ (internal artifact). Strip ciagent-internal provenance from synced docs (REQ-/D-/P-/CAP- IDs, milestone headers, .ciagent/PROJECT.md citations). Trim README.md (reusable deploy section, local key rotation paragraph). Fix version-tag drift (@v1.13→@v1.19, acdl/→nova/). ---ci--- project: acdl phase: 1 milestone: v1.20 status: execute requirements: [REQ-230, REQ-231, REQ-232] ---/ci---
88 lines
4.6 KiB
Markdown
88 lines
4.6 KiB
Markdown
# 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
|
||
|
||
1. **Before completing a task**, read the relevant skill file(s) that
|
||
match the task's domain.
|
||
2. **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."
|
||
3. **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`](../skills/api.md) | `domains/api/` | C1, C2, C6 | web API |
|
||
| [`security.md`](../skills/security.md) | `domains/security/` | C1 | cross-cutting (all 5) |
|
||
| [`data.md`](../skills/data.md) | `domains/data/` | C1, C4, C6 | web API, worker, scheduled job |
|
||
| [`testing.md`](../skills/testing.md) | `domains/testing/` | C1, C5 | UAT (citizen-dev RACI) |
|
||
| [`observability.md`](../skills/observability.md) | `domains/observability/` | C7 | basic observability bootstrap |
|
||
| [`errors.md`](../skills/errors.md) | `domains/errors/` | C1, C7 | web API, worker, scheduled job |
|
||
| [`devops.md`](../skills/devops.md) | `domains/devops/` | C5, C7, C8 | scheduled job, worker |
|
||
| [`infrastructure-as-code.md`](../skills/infrastructure-as-code.md) | `domains/infrastructure-as-code/` | C1, C5, C8 | static asset |
|
||
| [`compliance.md`](../skills/compliance.md) | `domains/compliance/` | C1, C5 | cross-cutting (all 5) |
|
||
|
||
## Atelier Provenance
|
||
|
||
The skills are derived from [Atelier](https://example.com/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) 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 |