Recurring features are standard Aigon features that create themselves. You write a spec template once, drop it in docs/specs/recurring/, and Aigon automatically instantiates it into your backlog at the start of each ISO week. No cron jobs, no remembering — routine work just appears.

How it works

On server startup and every 24 hours thereafter, Aigon scans docs/specs/recurring/ for templates marked schedule: weekly. For each template, it checks whether an open instance already exists for the current ISO week. If none does, it clones the template into docs/specs/features/01-inbox/ and immediately prioritises it — assigning an ID and moving it to backlog. When you open the dashboard on Monday, it’s already there waiting to be started.

Server starts / 24h tick
        ↓
Scan docs/specs/recurring/
        ↓
For each template: is an open instance for this week present?
   YES → skip (no duplicate)
   NO  → clone to inbox → prioritise → appears in backlog
        ↓
You start it like any other feature

The instantiated feature behaves exactly like a manually created feature — you can run it in Drive, Fleet, or Autonomous mode, review it, close it, or pause it. Done and paused instances don’t block the following week’s creation.

Template format

A recurring template is a standard feature spec with two extra frontmatter fields:

---
schedule: weekly
recurring_slug: weekly-dep-sweep
name_pattern: dependency-sweep-{{YYYY-WW}}
---
 
# Feature: dependency-sweep
 
## Summary
Run `npm audit` and `npm outdated`, write findings to `docs/reports/dep-sweep-{{YYYY-WW}}.md`, and close.
 
## Acceptance Criteria
- [ ] `npm audit` output captured with severity summary
- [ ] `npm outdated` output captured
- [ ] Findings written to docs/reports/dep-sweep-{{YYYY-WW}}.md
- [ ] Feature closed after report is written

The {{YYYY-WW}} placeholder is available in both name_pattern and the template body. Aigon replaces it with the ISO year and two-digit week number (e.g. 2026-17) when instantiating.

Directory layout

• docs/specs
  • recurring
    • weekly-dep-sweep.md
    • weekly-docs-gap-scan.md
    • your-custom-template.md
  • features

Templates in docs/specs/recurring/ are never surfaced on the dashboard or board — they are input templates only.

Built-in templates

Aigon ships two built-in recurring templates that aigon init places in docs/specs/recurring/:

Weekly dependency sweep

Slug: weekly-dep-sweep

Runs npm audit and npm outdated, writes a findings report to docs/reports/dep-sweep-{{YYYY-WW}}.md, and closes. Useful for keeping dependency health visible without making it anyone’s job to remember.

Good agent for this: cc (Claude Code) or cx (Codex) in Autonomous mode with --stop-after=close. The task is mechanical and self-contained.

Weekly docs gap scan

Slug: weekly-docs-gap-scan

Diffs changes to lib/ and templates/ since the last authoritative-doc commit (AGENTS.md, docs/architecture.md, docs/development_workflow.md), writes a gap report to docs/reports/docs-gap-{{YYYY-WW}}.md, and closes. Surfaces cases where code changed but documentation didn’t.

Good agent for this: cc (Claude Code) — reading code and writing prose is its strength.

CLI commands

# Check which templates are due and create any missing instances
aigon recurring-run
 
# List templates with their schedule, last created week, and due/not-due status
aigon recurring-list

recurring-run is safe to run manually at any time — it respects the same deduplication logic as the background scheduler and will not create duplicates.

Writing good recurring features

A recurring feature works best when:

It has a fixed, mechanical scope. The agent should be able to complete it without ambiguity. “Run npm audit, summarise findings, write report” is better than “improve code quality.”

It produces a persistent artefact. A report file, a PR, a commit — something that closes the loop. Features that just “check something” without an output are hard to verify as done.

It can close itself. The best recurring features are written so the agent can run aigon agent-status submitted and then close — no human review required. Add ## Agent instructions to the template body:

## Agent instructions
- Write the report to `docs/reports/dep-sweep-{{YYYY-WW}}.md`
- Run `aigon agent-status submitted` when done
- Do not open a PR — close directly with `aigon feature-close`

It has a clear done condition. Make the acceptance criteria checkable by the agent, not by a human reading prose.

Example: custom recurring feature

Here is a complete example template for a weekly changelog update:

---
schedule: weekly
recurring_slug: weekly-changelog
name_pattern: weekly-changelog-{{YYYY-WW}}
---
 
# Feature: weekly-changelog
 
## Summary
Summarise the week's merged features and commits into `CHANGELOG.md`.
Run `git log --oneline --since="7 days ago"` to collect the raw data,
then write a brief human-readable entry for this week.
 
## Acceptance Criteria
- [ ] `git log --oneline --since="7 days ago"` output reviewed
- [ ] New entry prepended to `CHANGELOG.md` with ISO week heading
- [ ] Entry includes feature numbers and one-line descriptions (no filler)
- [ ] Feature closed after CHANGELOG.md is committed
 
## Agent instructions
- Use `git log` — do not invent commits
- Keep entries concise: one line per feature
- Run `aigon agent-status submitted` when done, then close

Deduplication rules

Aigon uses the following precedence to decide whether a template is due:

1. Is there a file in 01-inbox/, 02-backlog/, 03-in-progress/, or 04-in-evaluation/ whose frontmatter carries recurring_slug: <slug> for the current ISO week? If yes → skip.
2. (Secondary) Does .aigon/recurring-state.json record a successful creation for this slug and week? If yes → skip.

05-done/ and 06-paused/ are intentionally excluded from the check — a closed or paused instance from the current week does not block creation of a new one (though in practice, you’d only close it once the work is done).

ISO week reference

Aigon uses ISO 8601 week numbering: weeks start on Monday, and the first week of the year is the one containing the first Thursday. The {{YYYY-WW}} placeholder produces values like 2026-01 through 2026-53.

This means a template due in week 2026-17 (Mon 20 Apr – Sun 26 Apr 2026) will produce exactly one instance during that window, regardless of how many times the server restarts or aigon recurring-run is called.