agentleFS
Sign inStart free
Autocss-comAutocss-com/ai/.agents/skills/session/SKILL.md

session

Skill1 starsChanged 2 months agoMITView on GitHub

Cross-session continuity and backlog/process rules — how project state, outstanding work, and documentation survive between sessions. Covers the session handoff, PROGRESS.json as the single backlog source, the GitHub Issues/Projects mirror, documentation maintenance, and the next-phase prompt. Use at the start and end of every session, and whenever tracking or handing off work.

17 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use debug, release and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AnthropicSkill

    debug

    Structured debugging session — reproduce, isolate, diagnose, and fix. Trigger with an error message or stack trace, "this works in staging but not prod", "something broke after the deploy", or when behavior diverges from expected and the cause isn't obvious.

    Also in 3 projects that use this

  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 4 projects that use this

  • GoogleSkill

    tdd

    Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 3 are distinctive, and 7 are very specific to this project.

  • 0

    Common

    Most of the 14 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read .agents/SESSION-HANDOFF.md before making any implementation decision.

    line 15
  2. Very specific:

    If the handoff conflicts with a skill, the architecture skill, or the canonical laws, stop and ask — never resolve silently (conflict …

    line 17
  3. Very specific:

    If the board/toolset is unavailable in a session, skip silently — PROGRESS.json stays authoritative and the mirror catches up later.

    line 35
  4. Very specific:

    Commit → update PROGRESS.json → append a session shard → update SESSION-HANDOFF.md → reconcile the GitHub mirror.

    line 39
  5. Very specific:

    Never starts implementing before reading SESSION-HANDOFF.md

    line 51
  6. Very specific:

    Never treats chat memory or the issue tracker as the backlog source — PROGRESS.json is

    line 52
  7. Very specific:

    Never stacks backlog + in-progress labels, or invents new status labels

    line 53
  8. Distinctive:

    Never resolves a documented-rule conflict silently — surface it to the user

    line 54
  9. Distinctive:

    Never ends a working session without updating state + writing the next-phase prompt

    line 55
  10. Distinctive:

    No version-sensitive web-platform features are referenced here — everything used is Baseline Widely available.

    line 61

“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Session

Work spans many sessions and many AI vendors. Continuity is a discipline, not an accident. State lives in files, not in memory; the backlog has one source of truth; the mirror is one-way.

Start of every session

  1. Read .agents/SESSION-HANDOFF.md before making any implementation decision.
  2. Re-assert the handoff's Constraint Lock before coding.
  3. If the handoff conflicts with a skill, the architecture skill, or the canonical laws, stop and ask — never resolve silently (conflict priority: Autocss-com/ai AGENTS.md > repo AGENTS.md > SESSION-HANDOFF.md).

Skipping handoff review "to save time" is prohibited — it is the single largest cause of lost context and repeated mistakes.

Single source of truth for outstanding work

PROGRESS.json (its meta.future_goals + cursor.open_q) is the one authoritative list of outstanding work. Keep structured state as data in PROGRESS.json; keep principles/rationale as concise prose in the skills/docs (JSON usually costs more tokens for prose).

Nothing competes with PROGRESS.json. Chat memory, scratch notes, and the issue tracker are all downstream of it.

The GitHub mirror is one-way

GitHub Issues + the Projects board are a human-visible mirror of the backlog, never a competing tracker:

  • Open an Issue for each new backlog / open-question item; close it when done.
  • Title mirrors the item; body carries detail + a pointer to the PROGRESS.json / prompt entry; apply the backlog label.
  • Board columns are label-driven and status labels are mutually exclusive — never stack them. Backlog column = backlog label only; In Progress = in-progress only (you must remove backlog when moving to In Progress); Done = the Issue closed (no status label). To move a card, swap the status label, never add a second. Grouping tags (e.g. demo) are orthogonal — keep them.
  • Issues are effectively append-only (GitHub closes, never deletes) — create deliberately, avoid duplicates.
  • If the board/toolset is unavailable in a session, skip silently — PROGRESS.json stays authoritative and the mirror catches up later.

End of every session (the ritual)

Commit → update PROGRESS.json → append a session shard → update SESSION-HANDOFF.md → reconcile the GitHub mirror. Then write the next-phase prompt: a super-detailed brief for what the next session must do, holding all three contexts (immediate task, overall project intent, next-phase needs) so no context is dropped.

Documentation maintenance (periodic, cost-driven)

Periodically optimize the docs for AI accessibility/usability, not human reading, to cut token cost — without dropping any detail, intention, plan, or context. Reduce redundancy; restate more concisely; prefer a short whitelist ("only X permitted; all else forbidden") over long blacklists when clearer for AI processing. Never duplicate a rule already stated — strengthen the existing wording instead (see the DRY principle).

Standards consultation

Consult the standing references — modern-web-guidance and MDN Web Docs (search / doc / compat) — and periodically reconcile them against the app's current features. Their content is advisory and subordinate: on any conflict, the AutoCSS rules win. But the requirement to consult, to reconcile, and to suggest improvements is canonical. Identify ≠ apply — never silently change anything; confirm with the user first.

What session-handling never does

  • Never starts implementing before reading SESSION-HANDOFF.md
  • Never treats chat memory or the issue tracker as the backlog source — PROGRESS.json is
  • Never stacks backlog + in-progress labels, or invents new status labels
  • Never resolves a documented-rule conflict silently — surface it to the user
  • Never ends a working session without updating state + writing the next-phase prompt

Baseline & support

Checked against MDN as of 2026-07-16.

  • No version-sensitive web-platform features are referenced here — everything used is Baseline Widely available.

Canonical rules: https://github.com/Autocss-com/ai/blob/main/AGENTS.md

Reference

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free