SubFrame - SubFrame Project

This project is managed with SubFrame. AI assistants should follow the rules below to keep documentation up to date.

Note: This file is named AGENTS.md to be AI-tool agnostic. CLAUDE.md and GEMINI.md contain a reference to this file.

Core Working Principle

Only do what the user asks. Do not go beyond the scope of the request.

Implement exactly what the user requested — nothing more, nothing less.
Do not change business logic, flow, or architecture unless the user explicitly asks for it.
If a user asks for a design change, only change the design. Do not refactor, restructure, or modify functionality alongside it.
If you have additional suggestions or improvements, present them as suggestions to the user. Never implement them without approval.
The user's request must be completed first. Additional ideas come after, as proposals.

Relationship to Native AI Tools

SubFrame enhances native AI coding tools — it does not replace them.

Claude Code works exactly as normal. Built-in features (/init, /commit, /review-pr, /compact, /memory, CLAUDE.md) are fully supported. CLAUDE.md is Claude Code's native instruction file — users can add their own tool-specific instructions freely. SubFrame adds a small backlink reference pointing to this AGENTS.md file using HTML comment markers ( / ). SubFrame will never overwrite user content in CLAUDE.md.

Gemini CLI works exactly as normal. Built-in features (/init, /model, /memory, /compress, /settings, GEMINI.md) are fully supported. GEMINI.md is Gemini CLI's native instruction file — same backlink approach as CLAUDE.md. Users can add their own instructions freely and SubFrame won't overwrite them.

Codex CLI gets SubFrame context via a wrapper script at .subframe/bin/codex that injects AGENTS.md as an initial prompt.

This file (AGENTS.md) contains SubFrame-specific rules that apply across all tools:

Sub-Task management (.subframe/tasks/*.md, index at .subframe/tasks.json)
Codebase mapping (.subframe/STRUCTURE.json)
Context preservation (.subframe/PROJECT_NOTES.md)
Internal docs and changelog (.subframe/docs-internal/)
Session notes and decision tracking

Session Start

Read these files at the start of each session:

.subframe/STRUCTURE.json — Module map, file locations, architecture notes
.subframe/PROJECT_NOTES.md — Project vision, past decisions, session notes
.subframe/tasks.json — Sub-task index (pending, in-progress, completed)

This gives you full project context before making any changes. The session-start hook (if configured) automatically injects pending/in-progress sub-tasks into your context, but you should still read these files for deeper understanding.

Concurrent Work & Worktrees

Before making changes, check whether other AI sessions or agent teams are already working on this repository. Signs of concurrent work include:

In-progress sub-tasks you didn't start (check .subframe/tasks.json)
Recent uncommitted changes in git status that aren't yours
Lock files or active worktrees (git worktree list)

If concurrent work is detected, ask the user: "Another session appears to be working on this project. Should I use a git worktree to avoid conflicts?"

Git worktrees create an isolated copy of the repo on a separate branch, allowing parallel work without merge conflicts:

Each worktree has its own working directory and branch
Changes in one worktree don't affect others until merged
Use worktrees when multiple agents or sessions work on different features simultaneously

When to suggest a worktree:

Agent teams spawning multiple workers on the same repo
User asks to work on a feature while another is in progress
The session-start hook flags concurrent sessions

When worktrees are NOT needed:

Single-session work with no concurrent agents
Read-only exploration or research tasks
Quick fixes that won't conflict with in-progress work

Hooks (Automatic Awareness)

SubFrame deploys 5 Claude Code hooks to .subframe/hooks/ in each project. These fire automatically — no manual intervention needed.

Hook	When it fires	What it does
SessionStart	Startup, resume, after compaction	Injects pending/in-progress sub-tasks into context
UserPromptSubmit	Each user prompt	Fuzzy-matches prompt against sub-tasks; writes user message signal to `agent-state.json` for terminal marker detection
Stop	When AI finishes responding	Reminds about in-progress sub-tasks; flags untracked work if source files changed
PreToolUse	Before each tool invocation	Writes real-time agent activity to `agent-state.json` (session, step, terminal ID binding)
PostToolUse	After each tool invocation	Marks steps completed in `agent-state.json`; ensures terminal ID binding

Hook configuration lives in .claude/settings.json (merged automatically on project init/healthcheck). Hooks use node .subframe/hooks/<name>.js commands.

Hook Template Deployment

Hook source of truth: src/shared/frameTemplates.ts → compiled to src/shared/frameTemplates.js → generated to scripts/hooks/*.js.

When hook templates change, all user projects need updating:

node scripts/build-templates.js — compile TS → JS
npm run generate:hooks — regenerate scripts/hooks/ and .subframe/hooks/ from templates
npm run verify:hooks && npm run verify:templates — confirm sync
Commit the updated frameTemplates.js and scripts/hooks/*.js
User projects: SubFrame Health Panel detects outdated hooks (via @subframe-version stamps) and offers "Update All"

The /release skill handles steps 1–4 automatically.

Skills (Slash Commands)

SubFrame provides optional slash commands for AI coding tools that support them (e.g., Claude Code):

Skill	Purpose
`/sub-tasks`	Interactive sub-task management — list, start, complete, add, archive
`/sub-docs`	Sync all SubFrame documentation after feature work (changelog, CLAUDE.md, PROJECT_NOTES, STRUCTURE)
`/sub-audit`	Code review + documentation audit on recent changes
`/onboard`	Bootstrap SubFrame files from existing codebase context

Skills are deployed to .claude/skills/ and enhance the workflow — but direct file editing always works as a fallback. If your AI tool doesn't support skills, follow the manual instructions in each section below.

Sub-Task Management

Terminology: "Sub-Tasks" are SubFrame's project task tracking system. The name plays on "Sub" from SubFrame and disambiguates from Claude Code's internal todo tools. When the user says "sub-task", they mean this system.

Sub-Task File Format

Each sub-task lives in its own markdown file at .subframe/tasks/<id>.md with YAML frontmatter:

---
id: task-abc12345
title: Short and clear title (max 60 characters)
status: pending | in_progress | completed
priority: high | medium | low
category: feature | enhancement | bug | fix | refactor | research | docs | test | chore
private: true          # optional — stored in .subframe/tasks/private/ (gitignored)
description: AI's detailed explanation — what, how, which files affected
userRequest: User's original prompt/request — copy exactly
acceptanceCriteria: When is this task done? Concrete testable criteria
blockedBy: []          # task IDs this depends on
blocks: []             # task IDs that depend on this
createdAt: ISO timestamp
updatedAt: ISO timestamp
completedAt: ISO timestamp | null
---

## Notes

[YYYY-MM-DD] Session notes, alternatives considered, dependencies.

## Steps

- [x] Completed step
- [ ] Pending step

A generated index is kept at .subframe/tasks.json for hooks and quick lookups. After creating or modifying task .md files, regenerate the index by reading all .subframe/tasks/*.md files (excluding archive/) and building the JSON with tasks grouped by status.

Private tasks are stored in .subframe/tasks/private/ (gitignored). They work identically to regular tasks — visible in UI, CLI, and hooks — but are excluded from the git-tracked tasks.json index and the private/ directory itself. Use --private when creating via CLI, or toggle the checkbox in the UI. To make a private task public: node scripts/task.js update <id> --public.

Sub-Task Recognition Rules

These ARE SUB-TASKS:

When the user requests a feature or change
Decisions like "Let's do this", "Let's add this", "Improve this"
Deferred work: "We'll do this later", "Let's leave it for now"
Gaps or improvement opportunities discovered while coding
Situations requiring bug fixes

These are NOT SUB-TASKS:

Error messages and debugging sessions
Questions, explanations, information exchange
Temporary experiments and tests
Work already completed and closed
Instant fixes (like typo fixes)

Sub-Task Creation Flow

Detect sub-task patterns during conversation
Check existing sub-tasks first — read .subframe/tasks.json to avoid duplicates
Ask the user: "I identified these sub-tasks from our conversation, should I add them?"
If approved, create .subframe/tasks/<id>.md with all required frontmatter fields
Regenerate the .subframe/tasks.json index

Sub-Task Content Rules

title: Short, action-oriented

OK: "Add tasks button to terminal toolbar"
Bad: "Tasks"

description: AI's detailed technical explanation

What will be done, how, which files affected
Minimum 2-3 sentences

userRequest: User's original words — copy verbatim for context preservation

acceptanceCriteria: Concrete, testable completion criteria

Sub-Task Status Updates

Before starting any work, check .subframe/tasks.json for an existing sub-task that matches. If found, set it to in_progress — do not create a duplicate.

pending → in_progress — immediately when you begin working (update updatedAt)
in_progress → completed — when done and verified (set completedAt, update updatedAt)
completed → pending — when reopening, add a note explaining why
After commit: check and update the status of all related sub-tasks
Incomplete work: If partially done at session end, leave as in_progress and add a notes entry

Sub-Task Lifecycle

If a sub-task grows beyond its original scope, split it — create new sub-tasks and reference the parent ID in notes
Cross-reference relevant commit hashes or PR numbers in notes
Update the description if the approach changes significantly

Priority Guidelines

high — Blocking other work or explicitly flagged as urgent by the user
medium — Normal feature work and standard bug fixes
low — Nice-to-have improvements, deferred items, minor polish

.subframe/PROJECT_NOTES.md Rules

When to Update?

When an important architectural decision is made
When a technology choice is made
When an important problem is solved and the solution method is noteworthy
When an approach is determined together with the user

Format

Free format. Date + title is sufficient:

### [YYYY-MM-DD] Topic title
Conversation/decision as is, with its context...

Update Flow

Update immediately after a decision is made
You can add without asking the user (for important decisions)
You can accumulate small decisions and add them in bulk

Organization Rules

Keep "Project Vision" at the top, then "Session Notes" in chronological order
Notes should capture the why (decisions, trade-offs, alternatives rejected), not the what (code structure belongs in STRUCTURE.json)
When the same topic spans multiple sessions, consolidate related notes under the original heading rather than creating duplicates
When notes grow beyond ~500 lines, consider archiving older session notes or grouping by month

Context Preservation (Automatic Note Taking)

SubFrame's core purpose is to prevent context loss. Capture important moments and ask the user.

When to Ask?

Ask the user: "Should I add this to .subframe/PROJECT_NOTES.md?" when:

A sub-task is successfully completed
An important architectural/technical decision is made
A bug is fixed and the solution method is noteworthy
"Let's do this later" is said (also add as a sub-task)
A new pattern or best practice is discovered

Importance Threshold

Would it take more than 5 minutes to re-derive or re-explain in a future session? If yes, capture it.

Always capture: Architecture decisions, technology choices, approach changes, user preferences discovered during work.

Never capture: Routine debugging steps, simple config changes, typo fixes.

Note failed approaches too — a brief "We tried X, it didn't work because Y" prevents future re-exploration of dead ends.

Completion Detection

Pay attention to these signals:

User approval: "okay", "done", "it worked", "nice", "fixed", "yes"
Moving from one topic to another
User continuing after build/run succeeds

How to Add?

DON'T write a summary — Add the conversation as is, with its context
Add date — In ### [YYYY-MM-DD] Title format
Add to Session Notes section — At the end of PROJECT_NOTES.md

When NOT to Ask

For every small change (it becomes spam)
Typo fixes, simple corrections
If the user already said "no" or "not needed", don't ask again for that topic

If User Says "No"

No problem, continue. The user can also say what they consider important themselves: "add this to notes"

.subframe/STRUCTURE.json Rules

This file is the map of the codebase.

When to Update?

When a new file/folder is created
When a file/folder is deleted or moved
When module dependencies change
When an IPC channel is added or changed
When an important architectural pattern is discovered (architectureNotes)

Full Schema

{
  "modules": {
    "main/moduleName": {
      "file": "src/main/moduleName.ts",
      "description": "What this module does",
      "exports": ["init", "loadData"],
      "depends": ["fs", "path", "shared/ipcChannels"],
      "functions": {
        "init": { "line": 15 },
        "loadData": { "line": 42 }
      }
    }
  },
  "ipcChannels": {
    "CHANNEL_NAME": {
      "direction": "renderer → main",
      "handler": "main/moduleName"
    }
  },
  "architectureNotes": {
    "topicName": {
      "issue": "Description of the pattern or concern",
      "solution": "How it was resolved"
    }
  }
}

Update Rules

The pre-commit hook (if configured) auto-updates STRUCTURE.json when source files in src/ are committed
When deleting files, remove their entries from modules and update any depends arrays that referenced them
When adding IPC channels, also add them to the ipcChannels section with direction and handler
architectureNotes is for structural patterns (e.g., circular dependency workarounds, init ordering). Use PROJECT_NOTES.md for decisions and session context
If function line numbers drift significantly after edits, re-run the pre-commit hook or update manually

.subframe/docs-internal/ Directory

This directory holds project documentation that doesn't belong in the root:

File	Purpose
`changelog.md`	Internal detailed dev log — notable changes grouped by date and domain
`*.md` (ADRs)	Architecture Decision Records for significant design choices

What goes here: Internal changelog detail, architecture decision records, internal reference docs. The user-facing changelog is CHANGELOG.md in the project root (keepachangelog spec).

What does NOT go here: User-facing docs (those go in docs/ or project root), task files (those go in .subframe/tasks/).

.subframe/QUICKSTART.md Rules

When to Update?

When installation steps change
When new requirements are added
When important commands change

Before Ending Work

After significant work (code changes, architecture decisions), verify SubFrame files are in sync:

Sub-Tasks — Was this work tracked? Check .subframe/tasks.json → create/complete as needed
PROJECT_NOTES.md — Any decisions worth preserving? Ask the user
Changelog — Does CHANGELOG.md (keepachangelog) have entries under [Unreleased]? Also update .subframe/docs-internal/changelog.md for detailed internal notes
STRUCTURE.json — Source files changed? The pre-commit hook handles this automatically if configured; otherwise update manually

The stop hook (if configured) will flag untracked work automatically.

General Rules

Language: Write documentation in English (except code examples)
Date Format: ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)
After Commit: Check sub-tasks (.subframe/tasks/*.md) and .subframe/STRUCTURE.json
Session Start: Read STRUCTURE.json, PROJECT_NOTES.md, and tasks.json before making changes
Don't Duplicate: Always check existing sub-tasks before creating new ones

This file was automatically created by SubFrame. Creation date: 2026-03-03

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

SubFrame - SubFrame Project

Core Working Principle

Relationship to Native AI Tools

Session Start

Concurrent Work & Worktrees

Hooks (Automatic Awareness)

Hook Template Deployment

Skills (Slash Commands)

Sub-Task Management

Sub-Task File Format

Sub-Task Recognition Rules

Sub-Task Creation Flow

Sub-Task Content Rules

Sub-Task Status Updates

Sub-Task Lifecycle

Priority Guidelines

.subframe/PROJECT_NOTES.md Rules

When to Update?

Format

Update Flow

Organization Rules

Context Preservation (Automatic Note Taking)

When to Ask?

Importance Threshold

Completion Detection

How to Add?

When NOT to Ask

If User Says "No"

.subframe/STRUCTURE.json Rules

When to Update?

Full Schema

Update Rules

.subframe/docs-internal/ Directory

.subframe/QUICKSTART.md Rules

When to Update?

Before Ending Work

General Rules