agentic_rails_context_starter — Rails Documentation Template

SHA-256: c775f27a8254e895c05a3c9b363b4b2b8d58d303ae2e75440c18ea08423fb6dc

2026-10-11T07:00:56.455Z

---
name: readme
description: Profiles, deterministic project generation, checks, and selective starter migration.
metadata:
  version: "4.0"
  agentic_rails_source_version: "4.0"
  owner: "Jarryd Adaens"
  repo: "agentic_rails_context_starter"
---
# Agentic Rails context starter

Create a small project context with explicit identity, commands, constraints, and
conditional reading. Core is the recommended starting profile. Generation requires
an explicit profile and host so automation never guesses the destination's policy.
The canonical framework overview is the [tooling README](../agentic_rails_tooling/AGENTIC_RAILS_README.MD).

| Profile | Generated content |
| --- | --- |
| `core` | `AGENTS.md`, project `README.md`, a short purpose/design note, baseline manifest, selected host wrapper. |
| `planned-delivery` | Core plus a concrete current plan with objective, acceptance, dependencies, and continuity. |
| `high-consequence` | Planned delivery plus explicit independent review scope, recovery procedure, and required checks. |

No profile silently installs skills, plugins, rules, memory, advisors, or personas.
Core has no required milestone, plan, numerical score, or per-story commit.
The optional milestone/backlog/harness reference material in this repository is
not copied by the generator. Adopt it selectively when actual work needs it.

## Generate

Python 3.10 or newer is sufficient; no third-party dependency is required.
From this starter's root, preview a fresh Core project:

```powershell
python scripts/starter.py generate --destination "D:/Code Projects/example" --profile core --host codex --name "Example" --repo example --owner "Project Owner" --purpose "A local tool that summarizes task status." --check "python -m unittest discover -s tests -v" --constraint "Keep task data on this machine." --dry-run
```

Remove `--dry-run` to write the reviewed selection. Supply only commands the actual
project uses. Repeat `--setup`, `--build`, `--check`, `--run`, and `--constraint` as needed.
Commands are recorded as data and are never executed by generation. Without a command,
the instructions explicitly say that none has been adopted; no success is fabricated.
Resolve `--name`, `--repo`, `--owner`, and `--purpose` before generation. Unresolved
identity placeholders and template tokens are rejected.

Repeat `--stack-pack` to declare specific pack identifiers (for example `wpf`, `qt`,
or `unreal`). The manifest and instructions record this explicit selection; the starter
does not copy rule bodies, install packs, or assert activation. Leave it empty until the
actual stack is known. Tooling owns pack contents and host-specific activation.

Delivery profiles additionally require `--objective` and at least one `--acceptance`.
Repeat `--dependency` for real dependencies. High consequence also requires
`--review-scope`, `--recovery`, and at least one `--check`. These become the current
plan's concrete controls; a human or supported independent reviewer may fulfill review.

| Host | Instruction entry point | Validation status |
| --- | --- | --- |
| `generic` | `AGENTS.md`; load using the host's project-instruction mechanism. | Generated structure tested. |
| `codex` | `AGENTS.md`. | Generated structure tested; fresh-session activation belongs to rollout. |
| `claude` | `CLAUDE.md` imports `AGENTS.md`. | Import structure tested; runtime activation untested here. |
| `cursor` | `.cursor/rules/project.mdc`, always applied, points to `AGENTS.md`. | Rule structure tested; runtime activation untested here. |

Unlisted hosts are unsupported by this generator. Host choice does not infer a stack.
WPF needs evidence beyond XAML; Qt and Unreal need distinct C++ stack selections.

## Safe reruns and updates

Generation may add context to a nonempty directory only when none of its target files
already exists. Any collision refuses the entire operation before writing. Unrelated
files remain intact. An identical rerun with the recorded inputs performs no writes,
including when project content or source templates have changed. Changed identity,
profile, host, or generation inputs are refused; use a separately reviewed migration.

The schema-versioned `.agentic-rails.json` records project identity, selected components,
inputs, source Git revision, source-content hash, rendered-content hash, and the exact
framework baseline plus SHA-256 for each generated file. A Git revision alone does not
describe uncommitted templates; content hashes disambiguate them. There is no timestamp,
absolute destination, or random identity in the output. Equivalent source and inputs
produce identical files in different destinations.

```powershell
python scripts/starter.py update --destination "D:/Code Projects/example" --dry-run
python scripts/starter.py update --destination "D:/Code Projects/example"
```

Update uses the previous framework baseline, current source rendered with recorded
inputs, and current project content. Disjoint line changes merge while project edits
remain outside the new framework baseline. Overlap, concurrent creation, or deletion
against a changed source refuses all writes with a diagnostic. Matching changes are
accepted. A project deletion remains deleted when source is unchanged. Retired source
files and historical paths are preserved. Linked destination paths and malformed or
tampered baselines are refused. Updates never modify product version sources.

Dry runs report exact affected paths and actions without creating directories. Normal
writes recheck file snapshots and replace files atomically; ordinary I/O failures roll
back applied file content. This is not a crash-safe transaction across the whole tree:
take a project snapshot before adoption or an important update. Empty directories may
remain after an I/O failure. No commit, push, or deployment is performed.

## Existing projects without a baseline

Do not fabricate a baseline from their current files or copy the starter over them.
Generate the desired profile into a separate review directory, compare it with the
project, and explicitly adopt only useful routing and policy changes. Keep project
identity, architecture, commands, historical plans, version sources, and published
versions intact. Only record ownership for content whose old baseline can be proven.
Automatic updates require a trustworthy generator manifest. Cross-project migration
is selective and never a bulk rewrite.

## Checks and fixture

Run `python scripts/check-starter.py` for all regression checks and instruction word
counts, or `python -m unittest discover -s tests -v`. Counts include mandatory host
imports once. The 400-800-word target is a review warning; necessary project constraints
are preserved. Global instructions and tool/skill catalogs are separate measurements.

The [fresh Core fixture](tests/fixtures/fresh-core/README.md) includes a working addition
feature and a regression check. It demonstrates ordinary work without a milestone or
delivery plan. Generation/update checks cover conflicts, nonempty targets, repeated
runs, identity resolution, ownership, paths, newline handling, and interruption hazards.
Use [AGENTS.md](AGENTS.md) for contributor routing and
[context/versioning-policy.md](context/versioning-policy.md) only if adopting that optional product policy.