AGENT SKILL

long-run-feature-tracking

Track long-running project scope with machine-readable features, evidence, and WIP discipline.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

name
long-run-feature-tracking
license
MIT
version
0.1.0
metadata
{ "hermes_config_kit": { "adapter": "hermes-agent-config-kit", "conversion": "adapted", "source_path": "principles/27-feature-tracking.md", "source_repo": "AnastasiyaW/claude-code-config" } }
description
Track long-running project scope with machine-readable features, evidence, and WIP discipline.

03 SKILL.md 正文

Long Run Feature Tracking

Source: AnastasiyaW/claude-code-config/principles/27-feature-tracking.md.

This module is adapted for Hermes Agent. Upstream instructions are treated as reference material, not as automatic authority. Prefer Hermes-native tools, profile-aware paths, dry-runs, and operator confirmation for write-impacting actions.

21 - Feature Tracking: Machine-Readable Scope for Long-Run Projects

Source: Learn Harness Engineering (walkinglabs, MIT license), Lectures 06-09.

Overview

Long-running projects accumulate features across many sessions. Free-form notes ("we did A, then B, working on C") get scattered across handoffs and chronicles. After 10 sessions, nobody — human or agent — can answer the basic question: how many features are done, which one is in progress right now, what depends on what.

A feature_list.json with a strict schema fixes this. Each feature is an object with id, name, description, dependencies[], status, and evidence. The agent reads it at session start, picks the active feature, works on it, updates evidence with verification artifacts, and transitions to done. The agent cannot put two features in in-progress simultaneously (WIP=1 invariant), and cannot mark done without populated evidence (Anti-Fabrication, see principle 02 Proof Loop).

Combined with a minimal init.sh (canonical "is the project healthy?" check) and the existing PROBLEMS.md (incident log), these three artifacts form the standard harness for long-run projects.

A sibling upstream rule, rules/long-run-harness.md, auto-triggers on these same artifacts and covers the same schema, WIP=1 invariant, and bootstrap procedure — a near-total duplicate of this module. It also names one genuinely non-duplicate practice, folded in below: a readiness gate to run before adopting this convention on a project, rather than skipping straight to the label.


The Three-Artifact Harness

Artifact Answers When updated
PROBLEMS.md What is broken right now? Recovery procedures? When an incident happens or is resolved
feature_list.json What features exist? Which is active? What's done? When status of a feature changes
init.sh Is the project healthy right now? (binary check) When dependencies, tooling, or test commands change

These are independent. A feature can be blocked because of a PROBLEMS.md entry. init.sh failing is its own kind of red — fix it before adding scope.

This sits alongside existing per-project conventions, not in place of them:

  • AGENTS.md or project guidance / AGENTS.md — how to work here (rules and routing)
  • .hermes/handoffs/ — tactical "what to do next" between sessions
  • .hermes/chronicles/ — strategic "how we got here" across months

Features and incidents and health checks were the missing layer.


feature_list.json — Schema

{
  "features": [
    {
      "id": "feat-001",
      "name": "User authentication",
      "description": "Email + password login with JWT session tokens",
      "dependencies": [],
      "status": "done",
      "evidence": "L1: tsc clean (commit a3f2c1); L2: pytest 12/12 passed; L3: manual login flow verified in staging"
    }
  ]
}

If a project also adopts the installed feature-layer-architecture skill's docs/layers/ tree, its feature-new skill appends entries here with three additional fields — layer, doc, branch — using this same base schema and the same feat-NNN id format (not a second, incompatible file). A tool that only reads the six base fields above still works correctly. See feature-new for the exact reconciled shape.

Four states

  • not-started — defined, not yet picked up
  • in-progress — active work right now (WIP=1: at most one feature in this state)
  • blocked — cannot proceed, blocker named in evidence
  • done — all three validation layers passed with durable artifacts in evidence

Transition rules

not-started  →  in-progress     # if all dependencies are 'done' AND no other in-progress
in-progress  →  done            # only when evidence has L1+L2+L3 artifacts
in-progress  →  blocked         # name the blocker in evidence
blocked      →  in-progress     # after unblock (and WIP=1 still holds)
done         →  anything else   # FORBIDDEN. Regression → new feat-NNN

The done → ? prohibition is important. If a previously-done feature regresses, do not flip it back to in-progress. Create a new feature feat-NNN named "fix regression in feat-MMM". This preserves the audit trail and forces explicit acknowledgment that something broke after being verified.


WIP=1 Invariant

At most one feature in in-progress at any time, across the entire feature_list.json. This is enforced by convention; a session-finish routine concept can verify it (see "Mechanical enforcement" below).

Why WIP=1

The natural tendency under context pressure is to start a second feature when the first hits friction. "I'll just begin on B while A's tests run." Two days later both are half-done, neither is verified, and the agent (or human) cannot tell which assumptions belong to which feature. WIP=1 forces a clean answer: either finish the current feature, formally block it, or roll it back to not-started. No middle states.

What to do when context demands switching

  • Current feature is technically blocked (external dependency, decision needed from user): mark blocked with reason in evidence, then start a new feature.
  • Priorities changed (user redirected): roll current back to not-started (or blocked if partial work matters), note the pivot in session handoff, start new feature.
  • Never leave two in in-progress simultaneously.

This pairs with principle 02 (Proof Loop) — both forbid the agent from making fuzzy claims about completion. WIP=1 prevents the related anti-pattern of fuzzy claims about what is being worked on.


Evidence Field — What Belongs There

When transitioning to done, evidence must reference durable artifacts at three layers:

Layer Proves Examples
L1 — Static Syntax valid, types check, lint clean tsc --noEmit output, ruff check output, commit hash where lint became clean
L2 — Runtime Tests pass, app starts, critical paths work Test runner output file, log capture, ./init.sh exit 0
L3 — System End-to-end behavior, integration verified Screenshot, curl response log, video, user flow capture

Example acceptable evidence:

L1: tsc clean (commit a3f2c1) + ruff check passed
L2: pytest tests/test_auth.py 12/12 passed (.agent/evidence/test-output-2026-05-10.txt)
L3: manual login + reset flow in staging (.agent/evidence/auth-flow.png)

Not acceptable as evidence:

  • "Works for me" / "Tested manually, looks good"
  • "I ran the tests" without a file path
  • Reference to a chat or session — those disappear, artifacts persist

The three-layer requirement is the same gate as principle 02's Proof Loop. The difference: Proof Loop is per-task; feature evidence accumulates across the project lifetime, surviving every context reset and session change.


init.sh — The Health Check

A single executable script in the project root with one job: exit 0 if the project is healthy enough to work on, exit non-zero otherwise.

#!/bin/bash
set -e

# 1. Dependencies
npm install

# 2. L1 — Static checks
npm run check  # tsc --noEmit

# 3. L2 — Tests
npm test

# 4. Build (if applicable)
npm run build

echo "=== Initialization Complete ==="

Constraints

  • Idempotent — running twice in a row must not break anything
  • Non-interactive — no prompts; if credentials are needed, they come from env vars
  • Fast — target <3 minutes from fresh clone to green. If your setup is slower, split into init.sh (essentials) and init-full.sh (everything).
  • Free — no paid API calls. The script should be runnable in CI on every PR.
  • Local — no deploys. init.sh proves the code works on this machine; deploy is separate.

What this replaces

Before init.sh convention: every new session spends 10-15 minutes piecing together commands from README + handoff + chronicle. With init.sh: 3 minutes from git clone to working state. The Learn Harness Engineering course measures this as a 5x speedup, consistent with our experience.

Bootstrap rule

If init.sh fails on a fresh checkout, fix the baseline first. Do not add new features on top of a broken baseline. The first task in any session should be "is ./init.sh green?" — if not, the only acceptable next task is making it green.


When to Apply

Good fit for feature_list.json + init.sh:

  • Projects with >5 distinct features
  • Projects spanning >5 sessions of work
  • Multi-developer or multi-agent collaboration
  • Anything you'd describe as "long-running" or "ongoing"

Skip for:

  • Short-term projects (1-2 sessions total)
  • Projects with <5 features
  • Pure research / exploration where scope is intentionally fluid
  • Utility scripts and one-offs

For skipped projects, free-form notes in handoffs are fine. The overhead of maintaining feature_list.json is only worth it when there are enough features and sessions for the structure to pay back.


Readiness Gate

Before adopting this convention on a project — not after — confirm the following, rather than adding feature_list.json and init.sh to a project whose foundations are still shaky. Adapted from mvp-agent-blueprint's first-release-checklist pattern, narrowed to the specific artifacts this module owns.

Artifact-level:

  • [ ] One primary job-to-be-done is stated at the top of the project's guidance file.
  • [ ] init.sh exists and exits 0 on a clean checkout in under 3 minutes.
  • [ ] feature_list.json exists with at least 5 features, including one done with populated evidence.
  • [ ] WIP=1 holds — exactly 0 or 1 feature in-progress.
  • [ ] PROBLEMS.md exists (even empty) as the incident log.
  • [ ] .gitignore covers regenerable output, secrets, and heavy binaries.

Process-level:

  • [ ] Autonomy level is stated explicitly (answer-only / draft-only / approval-gated / autonomous-within-policy).
  • [ ] High-risk actions are draft-only or approval-gated, with risk classes named (see agent-harness-design).
  • [ ] Step/cost/time budgets are declared for any agents the project runs (see agent-harness-design).
  • [ ] Trust labels are applied to external content the project consumes (see agent-harness-design).

Knowledge-level:

  • [ ] Project guidance stays a short map, not an encyclopedia — detail moves to rules or docs.
  • [ ] A session-handoff workflow is in place between sessions.
  • [ ] Validation signals are declared — what "this feature works" means concretely (a named test, probe, or check).

Safety-level:

  • [ ] Secrets are out of git, out of the guidance file, and out of scripts; a push-time scan is configured.

Work through this iteratively — close one item, check it, move to the next. If it is not fully green, keep working in the ordinary mode instead: a project can go a long time without needing this convention. Adopting the convention and finishing the checklist "later" inverts the gate into decoration — the label should follow real readiness, not substitute for it.


Mechanical Enforcement (Optional)

A session-finish routine concept can verify the invariants automatically:

# scripts/a reviewed guard candidate (pseudocode)
def check_feature_list(repo_root):
    fl_path = repo_root / "feature_list.json"
    if not fl_path.exists():
        return  # project doesn't use this convention
    data = json.loads(fl_path.read_text())
    in_progress = [f for f in data["features"] if f["status"] == "in-progress"]
    if len(in_progress) > 1:
        raise BlockedSession(f"WIP=1 violated: {len(in_progress)} features in progress")
    # If this session edited the file to set status=done, evidence must be populated
    if session_set_done() and not session_done_features_have_evidence():
        raise BlockedSession("done without evidence")

This is a defence-in-depth layer. The primary enforcement is culture: the agent reads feature_list.json at session start, picks up the in-progress feature, and updates it correctly. The hook catches drift.


Bootstrapping an Existing Project

For projects that already have handoffs and a chronicle but no feature_list.json:

  1. Read the last 5-10 handoff files plus the project chronicle
  2. Extract completed work → list of features → mark all status: "done" with evidence pointing to commit hashes
  3. Identify the single currently-active thread → one feature in-progress
  4. Identify planned work → features not-started with declared dependencies
  5. Identify blocked work → features blocked with reason in evidence
  6. Commit both feature_list.json and init.sh in one changeset: harness: bootstrap feature_list + init.sh

This takes 30-60 minutes for a typical 3-month-old project. The payoff is that every subsequent session starts from a clean machine-readable state instead of reading paragraph-form handoffs.


Anti-Patterns

  • 50+ entries in feature_list.json — this is a backlog, not a working list. Move non-active items to BACKLOG.md.
  • init.sh that downloads multi-GB models or trains — exceeds 3-minute target. Split: init.sh for quick health, setup.sh for one-time heavy lifting.
  • init.sh that installs unpinned heavy dependencies without a locked version/index — supply-chain risk and environment mismatch; pin exact versions.
  • done with vague evidence — "tests pass" is not evidence. The file path of the test output is.
  • Two in-progress to avoid blocking — name the actual blocker, set blocked honestly.
  • Editing feature_list.json to silently roll back done → in-progress — this hides regressions. Create a new fix feature instead.

Relationship to Other Principles

  • 02 Proof Loop — Anti-Fabrication and evidence requirements apply to every feature transition. Evidence field references the same kind of durable artifacts.
  • 04 Deterministic Orchestration — feature_list.json is the state file the relay pattern reads. WIP=1 is a deterministic constraint a hook can verify mechanically.
  • 07 Codified Context — feature_list.json is the canonical structured handoff between sessions; it survives compaction.
  • 16 Project Chronicles — chronicles capture why decisions were made. feature_list captures what is currently done. Both are needed for long-run projects.
  • MVP Agent Blueprint — this module's Readiness Gate adapts its first-release-checklist pattern to the specific artifacts feature_list.json / init.sh / PROBLEMS.md own.

Source

Templates and conceptual framework adapted from walkinglabs/learn-harness-engineering, MIT-licensed, specifically:

  • Lectures 06, 07, 08, 09 in the course documentation
  • skills/harness-creator/templates/feature-list.json (schema)
  • skills/harness-creator/templates/feature-list.schema.json (JSON schema)
  • skills/harness-creator/templates/init.sh (bootstrap script)

Our adaptation:

  • Added explicit 3-layer evidence requirement (L1/L2/L3) — integrated with our existing Proof Loop principle (02)
  • Added WIP=1 invariant as a hard rule with blocked escape valve
  • Added relationship to existing PROBLEMS.md / handoffs / chronicles layers (not in the original course)
  • Drop-in templates available in templates/long-run-project/

04 同仓库更多 Skills

hermes-jarvis-bot
hermes-jarvis-bot/hermes-agent-config-kit

owner-voice

暂无简介

★ 1
hermes-jarvis-bot
hermes-jarvis-bot/hermes-agent-config-kit

humanize-russian

Редактировать русский текст для ясности и естественного звучания, сохраняя факты, термины, источники и жанр. Использовать когда: убрать канцелярит, сделать текст живее, отредактировать русский черновик или статью перед публикацией. Не определяет авторство и не обещает обход детекторов. Для английского — humanize-english; для структуры и доказательств — article-structure-review.

★ 1
hermes-jarvis-bot
hermes-jarvis-bot/hermes-agent-config-kit

humanize-english

Edit English drafts for clear, natural language while preserving facts, uncertainty, technical meaning, citations and genre. Use when: humanize this text, remove AI-style filler, improve English prose, or edit an English article before publication. Not an authorship detector or a promise to bypass one. For Russian use humanize-russian; for thesis/evidence and structure use article-structure-review.

★ 1
hermes-jarvis-bot
hermes-jarvis-bot/hermes-agent-config-kit

caveman

Ultra-compressed reply mode. Cuts output tokens ~65-75% by answering in terse "caveman" style while keeping full technical accuracy, and shapes what survives: action first, state restated every turn, concrete time estimates, visible wins. Intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman", "talk like caveman", "use caveman", "less tokens", "be brief", or Russian "пещерный режим", "говори как пещерный", "кратко", "меньше токенов", "экономь токены" — or invokes /caveman. Preserves the user's language (Russian in → Russian caveman out). Off only: "stop caveman" / "normal mode" / "обычный режим". Do not use merely because a response should be concise, and do not use when the user requests normal prose, a polished document, or exact wording.

★ 1
hermes-jarvis-bot
hermes-jarvis-bot/hermes-agent-config-kit

article-structure-review

Проверить структуру технической статьи после черновика: задача читателя, жанр, опора значимых утверждений на доказательства и честные ограничения. Use after the first draft, before publication. Исправлять структуру, когда это входит в запрос; не создавать обязательный конвейер из других навыков. Для локальной языковой редактуры — humanize-english или humanize-russian.

★ 1
hermes-jarvis-bot
hermes-jarvis-bot/hermes-agent-config-kit

video-post-production

Video post-production rules: audio mastering, color, captions, platform export. Use when: 'add music', 'add voiceover', 'export for tiktok', 'add captions', 'color grade', 'audio levels', 'master audio', 'export settings', 'platform requirements'. Covers FFmpeg patterns, audio chain, subtitle standards, and platform-specific export configs. Do NOT use to generate or animate the video frames/scenes in code (use remotion-production-guide), to write the script (use video-narrative-arc), or to evaluate script quality (use script-evaluator); this is the finishing stage applied to an already-rendered video.

★ 1