# API Contract Domain Axes

Hearing axes for tasks that involve API contract design, client integration, or server endpoint implementation.

## Axis 1: API Schema Source

The canonical source of API contracts (request/response shapes, endpoints, RPC methods).

**Question choices**:
- OpenAPI / Swagger specification (file in repository or hosted URL)
- Protobuf definitions (file in repository)
- GraphQL schema (SDL file or introspection endpoint)
- TypeScript or other code-first contract definitions in the repository
- No formal contract (ad-hoc JSON)
- Not applicable

**Follow-up (when not N/A)**: Record the path or URL. When multiple contracts exist (public API, internal services), list each with its purpose.

## Axis 2: Mock Environment

How clients exercise the API without depending on the live server.

**Question choices**:
- Generated mocks from the schema (e.g., from OpenAPI / Protobuf tooling)
- Hand-written mock server in the repository
- Hosted mock service (URL)
- Live development server (no separate mock)
- Not applicable

**Follow-up (when not N/A)**: Record the entry command or URL. Note whether the mock is updated automatically when the schema changes.

## Axis 3: Authentication Method

How the API authenticates and authorizes requests.

**Question choices**:
- Bearer token (e.g., JWT) issued by an auth service
- API key in a header or query parameter
- Session cookie set by a separate login flow
- Mutual TLS
- No authentication
- Not applicable

**Follow-up (when not N/A)**: Record where credentials are obtained for development and testing. Reference the secret store axis from `backend.md` if applicable.

## Axis 4: Schema Change Process (When Relevant)

How breaking and non-breaking schema changes are reviewed and rolled out.

**Question choices**:
- Documented contract review process (link to the document)
- Versioned endpoints (e.g., `/v1/`, `/v2/`)
- Backward-compatible changes only, no formal versioning
- Not applicable

**Follow-up (when not N/A)**: Record the document path or the version negotiation rule.

## Domain Completion

After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. API-specific resources such as rate-limit configuration, gateways, contract-test infrastructure, management consoles, or third-party API documentation can be captured in that answer.

# Backend Domain Axes

Hearing axes for tasks that involve server-side, data, or storage work.

## Axis 1: Database Schema Source

The canonical source of the database schema (tables, columns, indexes, constraints).

**Question choices**:
- Migration files in the repository (e.g., a `migrations/` directory)
- Schema file in the repository (e.g., `schema.sql`, `prisma/schema.prisma`)
- Database MCP that introspects a live database
- External schema registry (URL or hosted catalog)
- No persistent database
- Not applicable

**Follow-up (when not N/A)**: Record the path, MCP name, or URL. If multiple databases exist (primary, analytics, cache), list each.

## Axis 2: Migration History

How schema changes are tracked over time.

**Question choices**:
- Versioned migration files in the repository
- ORM-managed migration tool (e.g., Alembic, Flyway, Prisma Migrate)
- Manual change log document
- No migration tracking
- Not applicable

**Follow-up (when not N/A)**: Record the directory path or tool entry command. Note whether migrations are applied automatically on deploy or manually.

## Axis 3: Secret Store

Where credentials, API keys, and other secrets are stored and accessed.

**Question choices**:
- Secret manager service (e.g., AWS Secrets Manager, Vault, GCP Secret Manager)
- Environment variables loaded from a `.env` file (development only)
- Encrypted file in the repository
- No secrets required
- Not applicable

**Follow-up (when not N/A)**: Record the access mechanism. Examples — service name, MCP name, retrieval command. Do NOT record actual secret values; record only how they are reached.

## Axis 4: Background Job Infrastructure (When Relevant)

How asynchronous work is dispatched and observed.

**Question choices**:
- Queue service (e.g., SQS, Pub/Sub, RabbitMQ)
- Cron / scheduled tasks managed by deployment platform
- In-process worker thread
- No background work
- Not applicable

**Follow-up (when not N/A)**: Record the queue or scheduler name and how to enqueue / inspect jobs.

## Domain Completion

After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Backend-specific resources such as third-party services, distributed caches, object storage, feature flags, or observability platforms can be captured in that answer.

# Frontend Domain Axes

Hearing axes for tasks that involve UI work (component implementation, screen design, visual adjustment, design system migration).

## Axis 1: Design Origin

The canonical source of the visual specification.

**Question choices**:
- Design tool (e.g., a hosted design platform)
- Specification file in the repository (e.g., `DESIGN.md`, `docs/design/...`)
- Public documentation URL
- Existing implementation only (no separate design source)
- Not applicable

**Follow-up (when not N/A)**: How is the source accessed? Examples — URL, file path, MCP name, manual screenshot. Record the literal access mechanism.

## Axis 2: Design System

Reusable component library and design tokens.

**Question choices**:
- Component library with MCP server access
- Component library with documentation URL
- Storybook or equivalent component catalog
- Internal package without external documentation
- No design system (ad-hoc components)
- Not applicable

**Follow-up (when not N/A)**: How is the component catalog accessed? Examples — Storybook URL, package name, internal documentation path, MCP name.

## Axis 3: Guidelines

Usage guidance, accessibility rules, anti-patterns, naming conventions for UI work.

**Question choices**:
- Project-level guideline file (e.g., `DESIGN.md`, `docs/guidelines/...`)
- External documentation site
- Inline guidance in the design system catalog
- No documented guidelines
- Not applicable

**Follow-up (when not N/A)**: Where are the guidelines located? Record the path or URL. If multiple guideline files exist for different concerns (CSS, accessibility, i18n), list each.

## Axis 4: Visual Verification Environment

How rendered output is confirmed during implementation.

**Question choices**:
- End-to-end test runner with screenshot capability
- Storybook or equivalent isolated component preview
- Browser automation tool (dedicated CLI or MCP server)
- Manual browser inspection only
- Not applicable

**Follow-up (when not N/A)**: What is the entry command or URL? Examples — CLI invocation, dev-server URL, Storybook port, MCP name.

## Domain Completion

After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Frontend-specific resources such as asset/font hosting, icon libraries, experiment dashboards, or analytics dashboards can be captured in that answer.

# External Resource Hearing and Storage

Content protocol for capturing or updating external-resource records. The owning workflow supplies the interactive question mechanism.

## When to Hear

| Condition | Action |
|-----------|--------|
| `docs/project-context/external-resources.md` does not exist | Run full hearing for the relevant domain(s) |
| File exists and covers the current decision | Use it without an update question |
| The governing request identifies changed environment facts | Run diff-only hearing for the named axes |
| A relevant axis is absent | Hear only the missing axis |
| Access failure or contradictory current evidence indicates possible staleness | Ask: "Update external-resources.md? (no / yes-full / yes-diff-only)". On `yes-full` run full hearing; on `yes-diff-only` hear the named stale axes; on `no` preserve the file and report the limitation |

## Domain Routing

Load the domain reference matching the current task:

| Task type | References to load |
|-----------|--------------------|
| Frontend (UI work) | [frontend.md](frontend.md) |
| Backend (server / data work) | [backend.md](backend.md) |
| API contract work | [api.md](api.md) |
| Infrastructure / deployment | [infra.md](infra.md) |
| Fullstack | Load only the references whose frontend, backend/data, API-contract, or infrastructure responsibilities are affected by the confirmed scope; a fullstack label alone does not activate infrastructure |

Each domain reference defines the axes and the question template.

## Two-Phase Hearing

1. **Structured hearing** — for each axis selected by the When to Hear and Domain Routing rules, present the choices listed in its domain reference (always include "Not applicable" as an option). For each non-N/A axis, follow up with an access-method question (URL / MCP name / file path / command).

2. **Self-declaration for a full hearing** — after the structured axes for all selected domains are complete, ask: "Are there any other external resources for this work that the structured questions did not cover? If yes, describe them in your next message." If additional resources are supplied, append them to the storage file under an "Additional resources" subsection. A diff-only or missing-axis hearing ends after its named axes because the existing project record already completed self-declaration.

For a full hearing, the two phases are sequential and self-declaration runs even if the user answered "Not applicable" to every structured axis.

## Storage Protocol

After hearing completes:

1. Build the project-tier content from the answers. Use [template.md](template.md) as the structure.
2. Write to `docs/project-context/external-resources.md`. Create the directory if absent.
3. When the calling workflow has a target UI Spec or Design Doc, also append or update the document's `## External Resources Used` section with the feature-tier subset (label references + feature-specific identifiers only).
4. Report the file paths back to the calling workflow.

## Quality Checklist

- [ ] Each axis answered has both a presence indicator and an access method, or is marked "Not applicable"
- [ ] A full hearing ran self-declaration even when all structured axes were "Not applicable"; a diff-only or missing-axis hearing stayed within its named axes
- [ ] Project-tier entries hold the environment facts (URL, MCP name, file path, command)
- [ ] Feature-tier rows hold a project-tier label and the feature-specific identifier
- [ ] When the project file already existed, each write traces to an explicit changed fact, a missing relevant axis, or a confirmed stale-evidence update decision

# Infrastructure Domain Axes

Hearing axes for tasks that involve deployment, environment configuration, or infrastructure-as-code work.

## Axis 1: IaC Source

The canonical source of infrastructure definitions.

**Question choices**:
- Terraform configuration in the repository
- Pulumi or CDK code in the repository
- Kubernetes manifests / Helm charts in the repository
- Cloud-provider-native templates (e.g., CloudFormation, Bicep, Deployment Manager)
- Manual console configuration (no IaC)
- Not applicable

**Follow-up (when not N/A)**: Record the directory path. Note whether plan/apply is automated via CI or run manually.

## Axis 2: Environment Configuration

How per-environment settings (development, staging, production) differ.

**Question choices**:
- Per-environment configuration files in the repository (e.g., `terraform/envs/`, `config/staging.yaml`)
- Environment variables managed by the deployment platform
- Workspace or stack abstraction in the IaC tool itself
- Single shared configuration (no per-environment differences)
- Not applicable

**Follow-up (when not N/A)**: Record where environment-specific values are stored and which environments exist.

## Axis 3: Secrets in Infrastructure

How infrastructure code references secrets without exposing them.

**Question choices**:
- Secrets sourced from a secret manager via IaC data lookup
- Secrets injected at apply time via environment variables
- Encrypted secret files committed alongside IaC
- No secrets in infrastructure
- Not applicable

**Follow-up (when not N/A)**: Record the lookup mechanism. Cross-reference the secret store axis in `backend.md` when the same store serves both runtime and IaC.

## Axis 4: Deployment Trigger

How infrastructure and application changes reach environments.

**Question choices**:
- CI pipeline triggered on merge to a specific branch
- Manual approval step in CI
- Local apply by an operator
- Deployment platform's auto-deploy on push
- Not applicable

**Follow-up (when not N/A)**: Record the pipeline name or platform and the branch / tag convention that triggers each environment.

## Domain Completion

After these axes, return to the parent skill. The parent asks one integrated self-declaration question after all selected domains are complete. Infrastructure-specific resources such as IaC state storage, runbooks, on-call information, observability/cost dashboards, or compliance logging targets can be captured in that answer.

# Storage Templates

Two templates: the project-tier file and the feature-tier section.

## Project-Tier Template

Path: `docs/project-context/external-resources.md`

```markdown
# External Resources

Last updated: YYYY-MM-DD

This file records the external resources available to this project and how to access them. AI agents and contributors consult this file when work depends on resources outside the repository. Feature-specific identifiers belong in the consuming UI Spec or Design Doc, not here — this file holds environment-stable facts only.

## Frontend

### Design Origin
- Status: <present / not applicable>
- Source type: <design tool / specification file / public documentation URL / existing implementation only>
- Location: <URL / repository path>
- Access method: <WebFetch / file read / MCP name / manual screenshot>

### Design System
- Status: <present / not applicable>
- Source type: <component library with MCP / component library with documentation URL / Storybook / internal package / no design system>
- Location: <URL / package name / repository path>
- Access method: <package import / WebFetch / MCP name>

### Guidelines
- Status: <present / not applicable>
- Source type: <project file / external URL / inline in design system / no guidelines>
- Location: <path or URL>
- Access method: <file read / WebFetch>

### Visual Verification Environment
- Status: <present / not applicable>
- Tool type: <E2E test runner / Storybook / browser automation MCP / manual>
- Entry: <CLI command / URL / MCP name>

## Backend

### Database Schema Source
- Status: <present / not applicable>
- Source type: <migration files / schema file / external registry / database MCP>
- Location: <path or URL>
- Access method: <file read / introspection command / MCP name>

### Migration History
- Status: <present / not applicable>
- Tool: <tool name>
- Location: <directory path>
- Apply trigger: <automated on deploy / manual>

### Secret Store
- Status: <present / not applicable>
- Service: <service name>
- Access method: <CLI command / SDK call / MCP name>

### Background Job Infrastructure
- Status: <present / not applicable>
- Service: <queue or scheduler name>
- Access method: <how to enqueue / inspect>

## API

### API Schema Source
- Status: <present / not applicable>
- Source type: <OpenAPI / Protobuf / GraphQL SDL / code-first>
- Location: <path or URL>
- Access method: <file read / WebFetch / introspection endpoint>

### Mock Environment
- Status: <present / not applicable>
- Source type: <generated from schema / hand-written / hosted service / live dev server>
- Entry: <command / URL>

### Authentication Method
- Status: <present / not applicable>
- Mechanism: <bearer token / API key / session cookie / mTLS>
- Credential source: <reference to secret store entry, or development-only mechanism>

### Schema Change Process
- Status: <present / not applicable>
- Process: <document path / versioning rule>

## Infrastructure

### IaC Source
- Status: <present / not applicable>
- Tool: <Terraform / Pulumi / CDK / Kubernetes manifests / native templates>
- Location: <directory path>
- Apply trigger: <CI automated / CI with approval / manual>

### Environment Configuration
- Status: <present / not applicable>
- Mechanism: <per-environment files / platform env vars / IaC workspaces / shared config>
- Environments: <list>

### Secrets in Infrastructure
- Status: <present / not applicable>
- Mechanism: <secret manager lookup / apply-time env vars / encrypted files>

### Deployment Trigger
- Status: <present / not applicable>
- Mechanism: <CI on merge / manual approval / local apply / platform auto-deploy>

## Additional Resources

Free-form list captured during the self-declaration phase. Each entry: name, purpose, location, access method.

- <name>: <purpose> — <location> — <access method>
```

Sections corresponding to domains the user marked "Not applicable" for every axis can be omitted entirely. Sections with at least one present axis must include all axes within that domain (mark unused axes as "not applicable" inline).