---
schema_version: 1
id: RAC-KTQ63DXJTEZ2
type: roadmap
---
# RAC v0.7.10 — Artifact Templates

## Status

Planned

## Context

RAC provides deterministic validation, inspection, and repository intelligence for
structured product artifacts.

As adoption grows, users need an easier way to create valid artifacts without copying
existing files, searching documentation, or memorizing required sections.

Today, artifact creation relies on users:

- Reading artifact documentation
- Copying existing examples
- Manually constructing Markdown headings
- Remembering required and optional sections
- Correcting structural mistakes after validation

This creates unnecessary friction before RAC can provide value.

RAC should make the correct path the easiest path.

Canonical templates should become a first-class RAC capability rather than existing
only as documentation examples or dogfood artifacts.

## Requirement

RAC shall provide canonical, deterministic templates for every supported artifact type
and expose them through a simple artifact creation command.

Users shall be able to create a valid artifact without manually reproducing its
required structure.

Representative usage:

```bash
rac new requirement
rac new decision
rac new roadmap
rac new prompt
rac new design
```

Generated artifacts shall:

- Use canonical RAC structure
- Be deterministic
- Remain human-readable
- Require no AI service
- Avoid overwriting existing files
- Be suitable for immediate editing
- Pass structural validation when required placeholder content is completed

## Outcomes

- Reduce artifact authoring friction.
- Provide one canonical template for each artifact type.
- Keep generated artifacts aligned with current validators.
- Improve onboarding for new users.
- Eliminate copy-and-modify workflows.
- Make artifact creation deterministic and AI-optional.
- Establish the creation foundation for future metadata and identity support.

## Initiatives

### Initiative 1 — Canonical Template Library

Add bundled templates for every supported artifact type.

Representative structure:

```text
src/rac/templates/
├── requirement.md
├── decision.md
├── roadmap.md
├── prompt.md
└── design.md
```

Each template shall:

- Represent the minimum useful artifact structure
- Include all required sections
- Clearly distinguish optional sections
- Avoid unnecessary example content
- Use stable heading order
- Remain aligned with artifact specifications
- Be packaged with the RAC distribution

Templates shall not depend on files from RAC's own dogfood repository at runtime.

The dogfood artifacts may demonstrate usage, but the packaged templates shall be the
canonical generation source.

---

### Initiative 2 — `rac new`

Introduce:

```bash
rac new <artifact-type>
```

Supported artifact types shall initially include:

```text
requirement
decision
roadmap
prompt
design
```

Representative examples:

```bash
rac new requirement
rac new decision
rac new roadmap
```

The command shall:

- Validate the requested artifact type
- Load the canonical bundled template
- Generate deterministic Markdown
- Write to a user-specified or derived output path
- Refuse to overwrite an existing file by default
- Return a usage error for unsupported artifact types
- Provide both human-readable and automation-friendly failure behavior

The exact output-path contract shall be defined during implementation review.

Possible forms include:

```bash
rac new requirement user-authentication.md
rac new requirement --output rac/requirements/user-authentication.md
```

The command should avoid interactive prompts in the first version.

---

### Initiative 3 — Output Naming Contract

Define a predictable filename strategy.

RAC shall not require a specific repository folder structure.

Users may place generated artifacts wherever their repository conventions require.

The command may derive a filename from a supplied title or slug, but generation must
remain deterministic.

The implementation contract shall define:

- Whether an output path is required
- Whether a title flag is supported
- How titles are converted to slugs
- How invalid path characters are handled
- How filename collisions are reported
- Whether extensions are added automatically

RAC shall not silently choose a different filename when the requested path already
exists.

---

### Initiative 4 — Template Discovery

Expose the supported template set through the CLI.

Representative command:

```bash
rac templates
```

Representative output:

```text
Available artifact templates:

- requirement
- decision
- roadmap
- prompt
- design
```

Machine-readable output should also be considered:

```bash
rac templates --json
```

Representative JSON:

```json
{
  "schema_version": "1",
  "templates": [
    "requirement",
    "decision",
    "roadmap",
    "prompt",
    "design"
  ]
}
```

Template discovery shall use the same canonical registry as `rac new`.

The supported template list must not be duplicated across CLI code and template
storage.

---

### Initiative 5 — Template Validation

Treat bundled templates as part of RAC's compatibility contract.

Tests shall confirm that:

- Every supported artifact type has a bundled template
- Every template can be loaded from the installed package
- Template headings match the artifact specification
- Required sections are present
- Template order is stable
- Generated output is deterministic
- Unsupported artifact types fail clearly
- Existing files are not overwritten
- Packaging includes all template resources

Where placeholder content intentionally prevents full semantic validation, tests shall
verify structural validity and document the expected editing step.

---

### Initiative 6 — Canonical Examples

Use the same template definitions to support documentation examples where practical.

RAC should avoid maintaining separate, drifting versions of:

- Generated templates
- README examples
- User documentation examples
- Test fixtures

The canonical template should be reusable by:

- `rac new`
- Tests
- Documentation generation or verification
- Future Explorer artifact creation
- Future IDE integrations

Documentation may add explanatory annotations, but the underlying artifact structure
should remain aligned with the canonical template.

---

### Initiative 7 — Service-Layer Creation API

Implement artifact generation as a reusable RAC Core capability rather than embedding
the behavior exclusively in the CLI.

Representative interface:

```python
generate_artifact_template(artifact_type: str) -> str
```

or:

```python
create_artifact(
    artifact_type: str,
    output_path: str,
) -> CreatedArtifact
```

The service layer shall own:

- Artifact type lookup
- Template loading
- Deterministic rendering
- Output collision checks
- Creation result modeling

The CLI shall remain a thin consumer.

This allows future consumers such as Explorer and IDE integrations to create artifacts
without reimplementing template logic.

---

### Initiative 8 — Prepare for Future Metadata and Identity

v0.7.10 shall establish the artifact creation path that later releases can extend.

v0.7.11 is expected to add:

- YAML frontmatter
- Repository identity configuration
- Opaque system-assigned artifact IDs
- Canonical metadata generation

The v0.7.10 design should therefore avoid assumptions that would make frontmatter
integration difficult.

Templates should be structured so that a future release can add:

```yaml
---
schema_version: 1
id: RAC-01JY4M8X
type: decision
---
```

without replacing the artifact creation architecture.

v0.7.10 does not need to generate system-assigned IDs unless that dependency is brought
forward explicitly.

## Implementation Contract

The following decisions are pinned for v0.7.10.

### CLI Shape

```bash
rac new <artifact-type> <output-path> [--json]
rac templates [--json]
```

- The output path is required and explicit. v0.7.10 derives nothing: no title flag,
  no slug generation, no automatic extension. The file is written exactly where the
  user says.
- Title and slug derivation remain available to a future release if demand appears.
- Both commands are non-interactive.

### Exit Codes

| Outcome | Exit code |
| --- | --- |
| Artifact created | `0` |
| Unsupported artifact type | `2` |
| Output file already exists | `2` (matches `rac ingest --apply` precedent) |
| Output parent directory missing | `2` (no automatic directory creation) |
| Packaged template missing | `1` (operational error) |

### JSON Contracts

`rac templates --json`:

```json
{
  "schema_version": "1",
  "templates": ["decision", "design", "prompt", "requirement", "roadmap"]
}
```

`rac new <type> <path> --json`:

```json
{
  "schema_version": "1",
  "created": true,
  "type": "requirement",
  "path": "rac/requirements/user-authentication.md"
}
```

### Template Source of Truth

- Bundled templates under `src/rac/templates/` are the canonical source for artifact
  creation, loaded via `importlib.resources`.
- The supported template set is derived from the artifact spec registry; no separate
  hand-maintained list exists in CLI code.
- `rac schema <type> --template` keeps its existing spec-derived output unchanged in
  this release (JSON/output contract stability). Whether it should later render the
  bundled creation template is deferred as an open decision.
- CI tests assert that every bundled template classifies as its artifact type and
  passes structural validation, preventing drift between templates and validators.

### Architecture

- `src/rac/core/templates.py` owns the template registry and resource loading.
- `src/rac/services/create.py` owns creation: type lookup, collision check, UTF-8
  write, and the `CreatedArtifact` result model.
- The CLI remains a thin adapter over the service.
- Rendering is structured as frontmatter-plus-body with frontmatter empty in this
  release, so v0.7.11 metadata integration extends rather than replaces the design.

## Output Contracts

Representative generated requirement:

```markdown
# Requirement Title

## Status

Proposed

## Context

Describe why this requirement exists.

## Requirement

Describe the required capability.

## Goals

- Define the intended outcome.

## Non-Goals

- Define what is explicitly out of scope.

## Acceptance Criteria

- Define observable evidence that the requirement is satisfied.
```

Representative generated decision:

```markdown
# ADR-XXX Decision Title

## Status

Proposed

## Context

Describe the decision context.

## Decision

Describe the selected decision.

## Consequences

### Positive

- Describe the benefits.

### Negative

- Describe the trade-offs.

## Alternatives Considered

Describe the alternatives and why they were not selected.
```

The exact canonical template contents shall be derived from the current artifact
specifications and approved during implementation review.

## CLI Behavior

Recommended outcomes:

| Outcome | Exit code |
| --- | --- |
| Artifact created | `0` |
| Unsupported artifact type | `2` |
| Invalid output path | `2` |
| Output file already exists | Operational or usage error according to RAC policy |
| Packaged template missing | Operational error |

The final exit-code mapping shall align with RAC's established CLI conventions.

## Tests

Coverage should include:

- All supported artifact types are listed.
- Every supported artifact type can be generated.
- Unsupported types return a clear error.
- Generated output is deterministic.
- Templates preserve canonical heading order.
- Required sections are present.
- Output files use UTF-8.
- Existing files are not overwritten.
- Nested output directories behave according to the documented contract.
- Packaged templates are available after installation.
- CLI and service-layer output match.
- Human and JSON template discovery use the same registry.
- Templates remain compatible with artifact classification.
- Templates remain compatible with structural validation.
- No AI service is invoked.
- No repository-specific dogfood file is required at runtime.

## Non-Goals

- AI-generated artifact content
- Interactive authoring wizards
- Full project scaffolding
- Repository restructuring
- Custom user-defined template engines
- Remote template registries
- Ticket or task creation
- Automatic product reasoning
- Automatic acceptance-criteria generation
- Mandatory frontmatter
- System-assigned artifact IDs in this release unless explicitly pulled forward

## Risks

### Template Drift

Templates may stop matching validators or artifact specifications.

Mitigation:

- Treat templates as tested product assets
- Derive supported types from a canonical registry
- Run template validation in CI

### Placeholder Ambiguity

Users may mistake placeholder text for valid completed content.

Mitigation:

- Use clear, concise instructional placeholders
- Document whether generated artifacts are structurally or fully valid
- Avoid realistic example prose in canonical templates

### CLI Scope Creep

`rac new` could expand into a complex interactive scaffolding system.

Mitigation:

- Keep v0.7.10 non-interactive
- Limit scope to one artifact at a time
- Defer project scaffolding and custom templates

### Future Metadata Migration

A template architecture tied only to Markdown body content could make frontmatter
support harder later.

Mitigation:

- Keep generation in a service layer
- Treat frontmatter and body as separable rendering concerns
- Design for v0.7.11 metadata integration

## Success Measures

- Users can create every supported artifact type through RAC.
- Generated files follow canonical RAC structure.
- Users no longer need to copy existing artifacts to get started.
- Templates remain synchronized with validators.
- Template generation works without AI or network access.
- Existing files are never overwritten silently.
- Explorer and other future consumers can reuse the same creation service.
- v0.7.11 can add metadata and IDs without replacing the creation architecture.

## Related Decisions

- ADR-001
- ADR-015
- ADR-025
- ADR-026

## Dependencies

- Canonical artifact specifications
- Artifact classification
- Package resource loading
- CLI command registration
- Existing validation behavior

## Follow-On Work

v0.7.11 shall extend artifact generation with:

- Repository-scoped identity configuration
- Canonical YAML frontmatter
- Opaque system-assigned IDs
- Metadata validation

v0.7.12 shall add:

- Artifact lookup
- ID resolution
- Human-friendly search