Feature Track

Lightweight, repo-native shared memory for AI coding agents.

Feature Track keeps Codex, Claude Code, and other AI coding tools aligned on each long-lived feature: its status, source-of-truth docs, decisions, risks, and recent changes.

Spec frameworks help agents plan the next change. Feature Track helps agents remember the feature.

It is not chat-history search, an opaque memory database, or a full spec-driven development framework. It is a portable, low-friction Markdown memory layer that lives inside your repo through docs/features/.

Why

AI coding agents are good at making changes, but they lose project context easily:

• feature knowledge is scattered across PRDs, API notes, plans, chats, and old commits
• agents repeat discovery because there is no current feature index
• stale plans can look authoritative after reality has changed
• switching tools, sessions, or agents often resets project memory
• small teams and solo developers usually do not want heavyweight process

Feature Track gives every important feature a small living track file plus a global index. The track does not replace your docs. It points to the docs that still matter and records the current truth.

Who It Is For

Feature Track is designed for:

• teams that want shared project memory without heavyweight process
• solo developers and indie hackers using AI coding tools
• brownfield projects with useful but scattered docs
• teams using Codex, Claude Code, or multiple agent tools
• projects that need traceable feature context across sessions

Core Idea

docs/features/
├── README.md              # global feature index
└── <feature-id>/
    ├── README.md          # current feature memory
    ├── prd/
    ├── api/
    ├── plans/
    └── archive/

Each feature track answers:

• What is true now?
• Which docs are the current source of truth?
• What decisions should future agents preserve?
• What risks, migrations, or rollout constraints matter?
• What changed recently?

Philosophy

• Memory, not ceremony.
• Current truth over stale specs.
• Link first, migrate later.
• Adopt in minutes, improve over time.
• Works with your docs, not around them.

Feature Track is built for brownfield projects first. You can start by linking existing PRDs, API docs, plans, and design notes instead of moving everything into a new system.

Quick Start

Codex Plugin

For Codex users, install Feature Track as a plugin first. Add the Feature Track marketplace:

codex plugin marketplace add JunsW/feature-track

Then open /plugins in Codex, install Feature Track, restart Codex or start a new thread, and ask Codex to use Feature Track for your project.

For example, ask Codex to initialize Feature Track, create a track for the feature you are working on, and keep docs/features/ updated as the work changes.

For local development from a cloned checkout:

codex plugin marketplace add .

The Codex plugin bundles the feature-tracking skill so Codex can create, read, and maintain feature memory in your repo.

Claude Code Plugin

For Claude Code users, add the Feature Track marketplace, install the plugin, and reload plugins:

/plugin marketplace add JunsW/feature-track
/plugin install feature-track@feature-track
/reload-plugins

For local development from a cloned checkout:

/plugin marketplace add .
/plugin install feature-track@feature-track
/reload-plugins

Then invoke the bundled skill with:

/feature-track:feature-tracking

The Claude Code plugin bundles the same feature-tracking workflow for Claude Code projects.

Ask Claude Code to initialize Feature Track, create a track for the feature you are working on, and keep docs/features/ updated as the work changes.

Direct CLI

If you are working from a cloned checkout or want a tool-agnostic path:

python3 cli/feature_track.py init --root .
python3 cli/feature_track.py add checkout --name "Checkout"
python3 cli/feature_track.py validate --root .

This creates:

docs/features/
├── README.md
└── checkout/
    ├── README.md
    ├── prd/
    ├── api/
    ├── plans/
    └── archive/

What Feature Memory Looks Like

This repository uses Feature Track on itself. The global index lives at docs/features/README.md:

| Feature | Status | Track | Source Of Truth | Updated | Notes |
|---|---|---|---|---|---|
| Codex Plugin | active | [README](codex-plugin/README.md) | [README](../../README.md), [plugin manifest](../../plugins/feature-track/.codex-plugin/plugin.json) | 2026-07-06 | Publish-ready Codex plugin wrapper for the existing Feature Tracking skill |
| Claude Code Plugin | active | [README](claude-code-plugin/README.md) | [README](../../README.md), [plugin manifest](../../plugins/feature-track-claude/.claude-plugin/plugin.json), [marketplace](../../.claude-plugin/marketplace.json) | 2026-07-06 | Marketplace-ready Claude Code plugin wrapper for the Feature Tracking skill |

A feature track keeps the current operational memory close to the docs and files that prove it:

## Current Status

Feature Track now targets a mature Codex plugin path for Codex users.

## Source Of Truth

- Product intro and install path: [README](../../../README.md)
- Plugin manifest: [plugin.json](../../../plugins/feature-track/.codex-plugin/plugin.json)

## Decisions

- Package the Codex path as a single-skill plugin first.
- Keep MCP servers, apps, and hooks out of v0.1.

See docs/features/codex-plugin/README.md and docs/features/claude-code-plugin/README.md for the full real tracks.

How Agents Use It

At the start of work, an agent reads docs/features/README.md, opens the relevant feature track, and follows the current source-of-truth links instead of rediscovering context from scratch. After changes, the agent updates the feature track with the actual outcome: changed behavior, decisions, risks, tests, and recent changes.

validate turns this from loose Markdown into checkable memory. It catches index drift, missing required sections, feature tracks missing from the global index, and broken local links before stale context spreads into future sessions.

How It Compares

Full spec-driven tools are useful when you want every change to move through proposals, spec deltas, task lists, and archive steps.

Feature Track is lighter. It focuses on long-term feature context rather than controlling every change. It is a good fit when you want AI agents to stop forgetting what a feature is, without forcing a new development lifecycle.

See docs/comparison.md for more detail.

Other Adapters

Feature Track is portable. The spec is the core; tool-specific files are adapters.

For normal Codex and Claude Code use, prefer the plugin paths in Quick Start. The adapter installers below are for local testing, migration, or users who want project-local files instead of marketplace plugins.

Install the local Codex skill adapter directly:

python3 cli/feature_track.py install codex

This copies the Codex skill to ~/.codex/skills/feature-tracking and prints a reminder to restart Codex. If the target already exists, the installer stops by default. Pass --backup to move the old install aside before copying the new one.

Avoid installing both the Codex plugin and the standalone Codex skill adapter unless you are testing adapter behavior; both expose the same feature-tracking workflow.

Install for Claude Code in the current project:

python3 cli/feature_track.py install claude-code --root .

This creates .claude/commands/feature-track-*.md command files. If CLAUDE.md already exists, the installer writes CLAUDE.feature-track.md with merge guidance instead of editing your file.

What The CLI Does

• init: create docs/features/README.md
• add: create a feature track and add it to the index
• validate: check index drift, required sections, and broken local links
• install codex: install the local Codex skill adapter
• install claude-code: generate Claude Code project instructions and commands

Validation is intentionally permissive by default so brownfield projects can adopt Feature Track gradually. Use --ci when you want stricter drift checks in automation.

Repository Layout

• .github/workflows/ci.yml: basic CI for CLI syntax and feature memory validation
• .claude-plugin/marketplace.json: repo marketplace for the Claude Code plugin
• .agents/plugins/marketplace.json: repo marketplace for the Codex plugin
• spec/feature-track-spec.md: neutral Feature Track spec
• cli/feature_track.py: lightweight no-dependency CLI
• plugins/feature-track/: Codex plugin package
• plugins/feature-track-claude/: Claude Code plugin package
• skills/codex/feature-tracking/: Codex skill adapter
• skills/claude-code/: Claude Code adapter snippets and commands
• templates/: reusable Markdown templates

Status

v0.1.0 is the first public release of Feature Track. The core format is intentionally simple: a global feature index plus one Markdown track per feature under docs/features/.

Today, Feature Track is best used as a lightweight documentation layer for Codex, Claude Code, or any agent workflow that can read and update files in your repo. The included plugins and CLI help create and validate that structure; the Markdown files remain the source of truth.

The document structure is designed to stay stable as the project grows.

Contributing

Contributions are welcome. Please keep the spec portable, adapters lightweight, and validation friendly to existing projects. See CONTRIBUTING.md.

License

Feature Track is released under the MIT License.