joycraft-session-end
Skill15 starsChanged 54 days agoMITView on GitHub
Wrap up a session — capture discoveries, verify, prepare for PR or next session
- Commits and pushes
In this repository70 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- joycraft-add-contextSkill
- joycraft-add-factSkill
- joycraft-bugfixSkill
- joycraft-collaborative-setupSkill
- joycraft-decideSkill
- joycraft-decomposeSkill
- joycraft-designSkill
- joycraft-gather-contextSkill
- joycraft-hardenSkill
- joycraft-implement-featureSkill
- joycraft-implement-level5Skill
- joycraft-implementSkill
- joycraft-interviewSkill
- joycraft-lockdownSkill
- joycraft-new-featureSkill
- joycraft-optimizeSkill
- joycraft-researchSkill
- joycraft-setupSkill
- joycraft-spec-doneSkill
- joycraft-tuneSkill
- joycraft-verifySkill
- release-docs-syncSkill
- joycraft-add-contextSkill
- joycraft-add-factSkill
- joycraft-bugfixSkill
- joycraft-collaborative-setupSkill
- joycraft-decideSkill
- joycraft-decomposeSkill
- joycraft-designSkill
- joycraft-gather-contextSkill
- joycraft-hardenSkill
- joycraft-implement-featureSkill
- joycraft-implement-level5Skill
- joycraft-implementSkill
- joycraft-interviewSkill
- joycraft-lockdownSkill
- joycraft-new-featureSkill
- joycraft-optimizeSkill
- joycraft-researchSkill
- joycraft-session-endSkill
- joycraft-setupSkill
- joycraft-spec-doneSkill
- joycraft-tuneSkill
- joycraft-verifySkill
- release-docs-syncSkill
- joycraft-add-contextSkill
- joycraft-add-factSkill
- joycraft-bugfixSkill
- joycraft-collaborative-setupSkill
- joycraft-decideSkill
- joycraft-decomposeSkill
- joycraft-designSkill
- joycraft-gather-contextSkill
- joycraft-hardenSkill
- joycraft-implement-featureSkill
- joycraft-implement-level5Skill
- joycraft-implementSkill
- joycraft-interviewSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 7 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
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
- Very specific: line 35
Owner resolution: look up the owner name in this order — (1) git config user.name, (2) value in your auto-memory joycraft-owner.txt if …
- Distinctive: line 37
Only capture what's NOT obvious from the code or git diff:
- Distinctive: line 58
If nothing surprising happened, skip the discovery file entirely.
- Distinctive: line 69
When you UPDATE a context doc, also bump (or add) its YAML frontmatter — the 2-field shared schema:
- Very specific: line 78
If the file already has the frontmatter, update the last_updated and last_updated_by fields in place.
- Distinctive: line 86
Run the project's validation commands.
- Very specific: line 105
Never write done for work nothing has validated — this validation run (step 2) is what licenses the graduation.
- Very specific: line 108
If working from a Feature Brief at docs/features/<slug>/brief.md, also check off completed specs in the decomposition table.
- Distinctive: line 116
Commit all changes including the discovery file (if created) and spec status updates.
- Very specific: line 122
Push immediately: Run git push origin <branch> — do not ask, do not hesitate.
- Distinctive: line 126
If AGENTS.md does NOT have autonomous git rules (or has "ASK FIRST" for pushing), ask the user before pushing.
- Very specific: line 130
Write this report to the style contract in docs/templates/reference/output-style.md.
- Very specific: line 151
Run run /clear in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.
- Distinctive: line 177
If all specs in the feature are complete, hand off to a feature-level wrap-up instead (PR review, etc.) — the Handoff block is just the …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
At skill entry, run node docs/.joycraft/check.mjs check --json --session <session-id> once, reusing JOYCRAFT_SESSION_ID if supplied or one ID chosen for this conversation. If the checker is missing or fails, continue the requested skill quietly without retrying setup. Offer updates only for display: true; current, postponed, off, and unknown stay quiet. If automaticUpdate is present, finish this skill, then run its exact command once from the project root: the candidate must verify every safety gate before applying. Other updates require approval. After an offer or automatic attempt, record it with node docs/.joycraft/check.mjs acknowledge <available-version> --session <session-id>. Apply updates only at this workflow boundary; after success, reinvoke the skill or restart the session to load changed instructions.
Session Wrap-Up — Feature Finisher
This is the once-per-feature finisher — the heavy bookend that runs once, when the feature's specs are done, not after every spec. It is the only validation gate in the loop and the single place that pushes and opens the PR.
Two-tier wrap-up. The light per-spec step is
joycraft-spec-done(status bumptodo → in-review+ commit, no validation/push/PR — it runs after each spec). This skill is the heavy counterpart: full validation, consolidate the discovery stubs spec-done left behind, graduate everyin-reviewspec todone, push, and open the PR. Seedocs/reference/spec-status-lifecycle.mdfor thetodo → in-review → donelifecycle.
Complete these steps in order.
1. Consolidate Discoveries
Why: Discoveries are the surprises — things that weren't in the spec or that contradicted expectations. They prevent future sessions from hitting the same walls.
This is the consolidation pass: joycraft-spec-done may have left terse 2-line discovery stubs during the feature (one per surprising spec). Curate and expand those stubs into proper discovery docs now, and capture anything else surprising from the feature as a whole. If any stubs exist at docs/discoveries/, consolidate them (merge related ones, expand each into the full format below); then create or update a discovery file at docs/discoveries/YYYY-MM-DD-topic.md. Lazy-create the docs/discoveries/ directory if it doesn't exist.
(Discoveries stay flat at docs/discoveries/ rather than per-feature, since they often span features and are read serendipitously rather than via a known path.)
The discovery file MUST start with YAML frontmatter — the 4-field personal schema:
---
status: todo
owner: <resolved name>
created: YYYY-MM-DD
feature: <slug-of-related-feature> # omit if not feature-tied
---Owner resolution: look up the owner name in this order — (1) git config user.name, (2) value in your auto-memory joycraft-owner.txt if present, (3) ask the user once and persist.
Only capture what's NOT obvious from the code or git diff:
- "We thought X but found Y" — assumptions that were wrong
- "This API/library behaves differently than documented" — external gotchas
- "This edge case needs handling in a future spec" — deferred work with context
- "The approach in the spec didn't work because..." — spec-vs-reality gaps
- Key decisions made during implementation that aren't in the spec
Do NOT capture: files changed (that's the diff), what you set out to do (that's the spec), or a step-by-step narrative of the session (nobody re-reads these). Use this format:
# Discoveries — [topic]
**Date:** YYYY-MM-DD
**Spec:** [link to spec if applicable]
## [Discovery title]
**Expected:** [what we thought would happen]
**Actual:** [what actually happened]
**Impact:** [what this means for future work]If nothing surprising happened, skip the discovery file entirely. No discovery is a good sign — the spec was accurate. While consolidating, also flag stale discoveries per the staleness rule in docs/reference/knowledge-lifecycle.md — an advisory list in your report, never an auto-delete.
1b. Update Context Documents
Escalation gate first: a fact enforceable as architecture, a deny pattern, or a CI check goes to $joycraft-harden, not prose (advisory — continue if declined). Then, if docs/context/ exists, quickly check whether this session revealed anything about:
- Production risks — did you interact with or learn about production vs staging systems? → Update
docs/context/production-map.md - Wrong assumptions — did the agent (or you) assume something that turned out to be false? → Update
docs/context/dangerous-assumptions.md - Key decisions — did you make an architectural or tooling choice? → Add a row to
docs/context/decision-log.md - Unwritten rules — did you discover a convention or constraint not documented anywhere? → Update
docs/context/institutional-knowledge.md
When you UPDATE a context doc, also bump (or add) its YAML frontmatter — the 2-field shared schema:
---
last_updated: YYYY-MM-DD
last_updated_by: <resolved name>
---If the file already has the frontmatter, update the last_updated and last_updated_by fields in place. If it doesn't, prepend a fresh block. Context docs are shared artifacts (no single owner) — the shared schema reflects that.
Skip this if nothing applies. Don't force it — only update when there's genuine new context.
2. Run Validation — the ONLY validation gate
This is mandatory and it is the only validation gate in the loop: joycraft-spec-done deliberately skips validation (it trusts implement's per-spec TDD), so this feature-level run is the single cross-spec safety net. Never skip it.
Run the project's validation commands. Check AGENTS.md for project-specific commands. Common checks:
- Type-check (e.g.,
tsc --noEmit,mypy,cargo check) - Tests (e.g.,
npm test,pytest,cargo test) - Lint (e.g.,
eslint,ruff,clippy)
Fix any failures before proceeding. If validation fails, stop — do NOT graduate specs to done and do NOT push.
3. Graduate Specs in-review → done
This step graduates the feature's finished specs to their terminal state. Because session-end runs once at the end, multiple specs may be waiting in in-review (one per spec the loop completed via joycraft-spec-done). Graduate all of them, in both systems (the queue JSON and the frontmatter must never disagree):
For each spec in docs/features/<slug>/specs/ (or docs/bugfixes/<area>/ for bugfixes — scan recursively) whose status is in-review:
- Queue JSON —
joycraft-mark-done <spec-id> --to done <specs-dir>(the--to donegraduation; find<spec-id>by matching the entry'sfile). - Frontmatter — edit the spec file's YAML
status:todone.
Rules:
- Only graduate specs that are
in-review. A spec still attodowas never started — leave ittodoand report it as remaining (the feature isn't fully done; see the PR gate in step 6). Graduate nothing beyond what was validated, per the "Keep Changes and Tests to What the Task Asks" block indocs/templates/reference/model-profile-claude-fable-5-1.md. - Never write
donefor work nothing has validated — this validation run (step 2) is what licenses the graduation. (Onceverify-in-loopships, an independent verify performs thein-review → donetransition; until then, this step does.) donemeans verified, not merged. A merged PR is a git fact, never a spec status — do not invent amergedstatus or any fourth state beyondtodo/in-review/done.
If working from a Feature Brief at docs/features/<slug>/brief.md, also check off completed specs in the decomposition table.
4. Scan Read Telemetry
Run npx joycraft telemetry. Report its one-line result and move on. When the command is unavailable or fails — no npx, package not installed, stale cache without the subcommand, offline — note that in one line and continue. A skipped scan is never a failure and must never block wrap-up; joycraft-optimize reports the gap as INACCESSIBLE evidence.
5. Commit
Commit all changes including the discovery file (if created) and spec status updates. The commit message should reference the spec if applicable.
6. Push and PR (if autonomous git is enabled)
Check AGENTS.md for "Git Autonomy" in the Behavioral Boundaries section. If it says "STRICTLY ENFORCED" or the ALWAYS section includes "Push to feature branches immediately after every commit":
- Push immediately. Run
git push origin <branch>— do not ask, do not hesitate. - Open a PR if the feature is complete. The feature is complete when every spec is
done(none left attodo/in-review). Check the queue JSON / decomposition table — if all specs aredone, rungh pr createwith a summary of all completed specs. Do not ask first. - If specs remain (
todo), still push. The PR comes when the feature's last spec is graduated.
If AGENTS.md does NOT have autonomous git rules (or has "ASK FIRST" for pushing), ask the user before pushing.
7. Report and Hand Off
Write this report to the style contract in docs/templates/reference/output-style.md.
Feature complete.
- Feature: [slug]
- Specs graduated to done: [N] (remaining at todo: [N])
- Build: [passing / failing]
- Discoveries: [N consolidated / none]
- Pushed: [yes / no — and why not]
- PR: [opened #N / not yet — N specs remaining]
- Next: [what comes after this feature]End with the canonical Handoff block. Include any discovery and updated-context paths produced.
Recommended Next Steps
Next:
$joycraft-implement docs/features/<slug>/specs/<next-spec>.mdRun run /clear in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app first.
Then hand off with a briefing, not a bare command — a prompt the human pastes into the fresh session after run /clear in the CLI, or press Cmd+N (Ctrl+N on Windows/Linux) for a new thread in the desktop/IDE app. Fill every line; a cold agent must be able to act on this block alone without re-deriving context.
$joycraft-implement docs/features/<slug>/specs/<next-spec>.md
You are picking up the spec queue for <slug>, last session ended <date>.
Decisions <ids> are stamped in the brief — do not reopen them.
Start: <next-spec>.md (mode: <mode>). Order: specs/README.md.
Hazard: <the one known trap, or "none known">.
Done when: <next-spec> is in-review, committed, and the suite is green.Filled example:
$joycraft-implement docs/features/2026-07-29-succinct-gates/specs/gate-contract-tests.md
You are picking up the spec queue for 2026-07-29-succinct-gates, last session ended 2026-07-29.
Decisions D1-D7 are stamped in the brief — do not reopen them.
Start: gate-contract-tests.md (mode: batch). Order: specs/README.md.
Hazard: the suite regenerates bundles; commit machine-generated output as-is.
Done when: gate-contract-tests is in-review, committed, and the suite is green.If all specs in the feature are complete, hand off to a feature-level wrap-up instead (PR review, etc.) — the Handoff block is just the slash command for whatever the next move is.
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
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.

