| name | record-session |
| description | Records completed work progress to .trellis/workspace/ journal files after human testing and commit. Captures session summaries, commit hashes, and updates developer index files for future session context. Use when a coding session is complete, after the human has committed code, or to persist session knowledge for future AI sessions. |
[!] Prerequisite: This skill should only be used AFTER the human has tested and committed the code.
Do NOT run git commit directly — the scripts below handle their own commits for .trellis/ metadata. You only need to read git history (git log, git status, git diff) and run the Python scripts.
Portability rule: Run all commands from the repository root with repo-relative paths (./.trellis/scripts/...). Never hardcode user names, absolute paths, local home directories, or machine-specific workspace paths. The active developer is resolved from .trellis/.developer; if it is missing, first auto-resolve from TRELLIS_DEVELOPER, git config user.name, git config user.email local-part, or a unique existing .trellis/workspace/<developer>/. Only ask the collaborator for the developer id when those signals still cannot determine one uniquely.
Record Work Progress
Step 1: Get Context & Check Tasks
python3 ./.trellis/scripts/get_context.py --mode record
If this still reports that the developer is not initialized after auto-resolution, ask the collaborator for the developer id, then run:
python3 ./.trellis/scripts/init_developer.py <developer-id>
python3 ./.trellis/scripts/get_context.py --mode record
[!] Archive tasks whose work is actually done — judge by work status, not the status field in task.json:
- Code committed? → Archive it (don't wait for PR)
- All acceptance criteria met? → Archive it
- Don't skip archiving just because
status still says planning or in_progress
python3 ./.trellis/scripts/task.py archive <task-name>
Step 2: One-Click Add Session
python3 ./.trellis/scripts/add_session.py \
--title "Session Title" \
--commit "hash1,hash2" \
--summary "Brief summary of what was done"
cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --title "Title" --commit "hash"
| Feature | Description |
|---------|-------------|
| New API | Added user authentication endpoint |
| Frontend | Updated login form |
**Updated Files**:
- `packages/api/modules/auth/router.ts`
- `apps/web/modules/auth/components/login-form.tsx`
EOF
Auto-completes:
- [OK] Appends session to journal-N.md
- [OK] Auto-detects line count, creates new file if >2000 lines
- [OK] Auto-detects Branch context (
--branch override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
- [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
After running the script, verify with:
git log -1 --oneline
git status --short
Report both the code commit hash and the Trellis record commit hash. If .trellis/workspace or .trellis/tasks still has unstaged/uncommitted changes, report the exact blocker instead of claiming the session was recorded.
Script Command Reference
| Command | Purpose |
|---|
python3 ./.trellis/scripts/get_context.py --mode record | Get context for record-session |
python3 ./.trellis/scripts/add_session.py --title "..." --commit "..." | One-click add session (recommended, branch auto-complete) |
python3 ./.trellis/scripts/task.py archive <name> | Archive completed task (auto-commits) |
python3 ./.trellis/scripts/task.py list | List active tasks |
