Generator CLI reference

scripts/create-context-file.sh writes a date-prefixed context file into a typology subfolder and prints the created path.

Synopsis

scripts/create-context-file.sh --type <typology> --title "<title>" [options]
# optional body content is read from stdin

Options

Flag	Argument	Purpose
`-t`, `--type`	`TYPE`	Typology / subfolder (required). Validated against `KNOWN_TYPES`.
`-T`, `--title`	`TITLE`	Human-readable title (required); also seeds the slug.
`-s`, `--slug`	`SLUG`	Override the auto-derived slug.
`-g`, `--tags`	`TAGS`	Comma-separated tags for frontmatter.
`-R`, `--related`	`PATHS`	Comma-separated relative paths to related `.context` files. Omitted entirely from frontmatter when empty — never written as `related: []`.
`-b`, `--blocks`	`PATHS`	Comma-separated relative paths to `.context` files that cannot be ready until this file is done. Same omit-when-empty rule as `--related`.
`-k`, `--blocked-by`	`PATHS`	Comma-separated relative paths to `.context` files that must be done before this file is ready. Same omit-when-empty rule as `--related`. Read by the `context-index` skill’s `scripts/context-ready.sh`.
`--severity`	`LEVEL`	Follow-ups only. `CRITICAL`, `HIGH`, `MEDIUM` or `LOW` (case-insensitive, written upper case). Required together with `--priority` and `--graded`.
`--priority`	`LEVEL`	Follow-ups only. `P1`, `P2` or `P3` (case-insensitive, written upper case). Required together with `--severity` and `--graded`.
`--graded`	`DATE`	Follow-ups only. `YYYY-MM-DD`, the day the user confirmed the grades. No default.
`-d`, `--date`	`DATE`	Override the date (`YYYY-MM-DD`); defaults to today.
`-r`, `--root`	`DIR`	Context root; defaults to `.context`.
`-A`, `--allow-new-type`		Permit a typology not in `KNOWN_TYPES`.
`-n`, `--dry-run`		Print the target path and file body; write nothing.
`-f`, `--force`		Overwrite an existing target file.
`-h`, `--help`		Show usage.

Behavior

The output path is <root>/<typology>/<YYYY-MM-DD>-<slug>.md, where <root> is resolved against the current working directory (the consuming project).
The slug is derived from the title (lowercased, non-alphanumeric runs collapsed to single hyphens) unless --slug overrides it.
The date must match YYYY-MM-DD; other formats are rejected.
An unknown typology is rejected unless --allow-new-type is passed.
An existing target file is never overwritten unless --force is passed.
--severity, --priority and --graded are set together: any one without the other two is an error, as is a value outside the lists above, a malformed --graded, or any of them on a typology other than follow-ups. They are written last in the frontmatter, just before the closing ---, in the order severity, priority, graded. Pass them only after the user has confirmed the grades; see Follow-up grading.

Examples

# Finding with tags
scripts/create-context-file.sh --type findings --title "Auth token analysis" \
  --tags "auth,oauth"

# Finding that references an existing plan
scripts/create-context-file.sh --type findings --title "Auth token analysis" \
  --related "../plans/2026-03-16-auth-rollout.md"

# Follow-up that can't start until a plan is done
scripts/create-context-file.sh --type follow-ups --title "Wire up token refresh" \
  --blocked-by "../plans/2026-03-16-auth-rollout.md"

# Follow-up with grades the user has confirmed
scripts/create-context-file.sh --type follow-ups --title "Wire up token refresh" \
  --severity HIGH --priority P2 --graded 2026-10-07

# Plan with a heredoc body
scripts/create-context-file.sh --type plans --title "Retriever rollout" << 'EOF'
## Phase 1
...
EOF

# Preview only
scripts/create-context-file.sh --type merge-requests --title "PROJ-1234 retriever" --dry-run