---
phase: 07-main-session-skill
plan: 01
subsystem: session-orchestration
tags: [hermes, skil.md, session, jira, confluence, hindsight]

requires:
  - phase: 05-hindsight-memory-provider
    provides: hindsight_recall, hindsight_retain tools for cross-session memory
  - phase: 06-default-repos-ssh-mount
    provides: DEFAULT_REPOS mounted at /workspace/, ngn-jira/ngn-confluence/ngn-bitbucket scripts

provides:
  - Session lifecycle orchestration SKILL.md (init→work→close pattern)
  - Jira Task ticket creation procedure with epic cache management
  - Confluence doc search and load by ngn-agent tag
  - Automatic session summary save to hindsight
  - Cross-session similarity detection via hindsight_recall

affects:
  - Phase 8 cron reporting (daily reporting, stale archive deferred)

tech-stack:
  added: []
  patterns:
    - Hermes SKILL.md with 7-step procedural workflow
    - Cross-tool orchestration (hindsight_recall → ngn-jira → ngn-confluence → hindsight_retain)
    - User-confirmation gates before all Jira/Confluence mutations
    - Epic cache management via hindsight_retain with tier: epic-cache

key-files:
  created:
    - ~/.hermes/skills/ngn-agent/session/SKILL.md — Main session lifecycle skill (249 lines)
  modified: []

key-decisions:
  - "Set name: session in frontmatter (not ngn-agent-session) for skill_view('session') discoverability"
  - "Direct ngn-jira/ngn-confluence CLI commands in procedure instead of cross-skill_view loading"
  - "Epic cache refresh strategy: refresh every 24h or on explicit user request"
  - "Session summary uses structured plain text with fields: Date, Task, Repos, Jira, Key Decisions, Outcomes, Next Steps"
  - "Deferred ideas (daily reporting, stale archive, auto-create) explicitly excluded from skill content"

patterns-established:
  - "Session lifecycle: hindsight_recall → Jira prompt → Confluence prompt → Work → Jira update → Confluence update → hindsight_retain"
  - "All Jira/Confluence mutations gated behind user confirmation"
  - "hindsight_retain uses tier field for memory categorization (epic-cache, session-summary)"

requirements-completed: [SKIL-04]

duration: 12min
completed: 2026-06-15
---

# Phase 7 Plan 01: Main Session Skill Summary

**Hermes session SKILL.md at ~/.hermes/skills/ngn-agent/session/SKILL.md — 249-line session lifecycle covering init (hindsight recall), prompt (Jira/Confluence), work, close (Jira update, Confluence update, automatic hindsight save)**

## Performance

- **Duration:** 12 min
- **Started:** 2026-06-15T20:26:00Z
- **Completed:** 2026-06-15T20:38:00Z
- **Tasks:** 2
- **Files modified:** 1 (outside repo — system skill file at ~/.hermes/)

## Accomplishments

- Created `session/SKILL.md` with 7-step procedure covering the full session lifecycle
- All 14 decisions (D-01 through D-14) implemented and verified
- Skill is discoverable via `hermes skills list` as `session` under `ngn-agent` category
- All 5 required sections present: When to Use, Important, Procedure, Pitfalls, Verification
- 6 pitfalls documented (skill not loaded, epic cache stale, Confluence tag mismatch, Jira project 404, empty recall, context eviction)
- Automatic session summary save to hindsight (Step 7) — no user prompt (D-12)
- All write operations gated behind user confirmation (D-08, D-11)
- No deferred ideas (daily reporting, stale archive, auto-create) appear in skill content

## Task Commits

Each task was completed and verified. The skill file resides outside the project git repository (`~/.hermes/` is not a git repo), so no git commits were created for the individual tasks. The SUMMARY.md commit captures the plan completion metadata.

1. **Task 1: Create session/SKILL.md** — `~/.hermes/skills/ngn-agent/session/SKILL.md` created (249 lines, all sections present, all key content differences from RESEARCH.md example implemented)
2. **Task 2: Verify skill discoverability, structure, and decision coverage** — All 14 decisions D-01 through D-14 verified PASS, all 5 sections present, no deferred ideas found, discoverability confirmed via `hermes skills list`

**Plan metadata:** See final metadata commit for SUMMARY.md.

_Note: Skill file is outside git repo — tracked as external artifact._

## Files Created/Modified

- `~/.hermes/skills/ngn-agent/session/SKILL.md` — Main session lifecycle skill (249 lines, created)

## Decisions Made

- **Skill name**: Set `name: session` in frontmatter (not `ngn-agent-session`) to match the directory name and enable `skill_view("session")` discovery. The RESEARCH.md example used `ngn-agent-session` but the plan specified `session` for cleaner discoverability.
- **Epic cache mechanism**: Epics cached in hindsight with `tier: "epic-cache"`. Cache refreshed when >24h old or on explicit user request. The procedure checks cache age from the cached content timestamp.
- **Hindsight tool calls**: Represented with plain text code blocks (not `bash` language tag) since they are Hermes tool calls, not CLI commands. CLI commands (ngn-jira, ngn-confluence) use `bash` language tag.
- **No cross-skill loading**: Session procedure uses direct `ngn-jira` and `ngn-confluence` CLI commands instead of calling `skill_view("jira-query")` or `skill_view("confluence-search")`. This avoids context replacement issues and keeps the procedure self-contained.

## Deviations from Plan

None — plan executed exactly as written.

### Key Content Corrections from RESEARCH.md Example

The plan explicitly noted 4 corrections to apply vs. the RESEARCH.md reference example, all implemented:
1. ✅ `name: session` (not `ngn-agent-session`) in frontmatter
2. ✅ D-08 explicit: "Do NOT transition tickets (close, resolve, move to Done) without explicit user confirmation" in Step 5
3. ✅ Context-eviction reload reminder in Important section ("reload via `skill_view("session")`") and Pitfalls
4. ✅ Step 7 hindsight_retain is clearly unconditional ("Do NOT ask the user — this step is automatic and unconditional")

## Issues Encountered

- The skill file at `~/.hermes/skills/ngn-agent/session/SKILL.md` is outside the project git repository. No git commits possible for the individual task files. The file is a Hermes system skill and is not tracked in the ngn-agent project repo. This is expected — Hermes skills live under `~/.hermes/`, not in the project directory.

## Threat Flags

None — all threat mitigations from the plan's threat model are implemented:
- T-07-01: Jira tampering mitigated via D-08 (user confirmation gates in Step 5, Important section)
- T-07-02: Confluence tampering mitigated via D-11 (user confirmation gates in Step 6, Important section)
- T-07-03: Information disclosure mitigated via D-13 (structured task-level summary, no raw conversation in hindsight_retain)

## Next Phase Readiness

- Session skill fully ready for `skill_view("session")` loading
- Phase 8 (cron reporting, stale archive) can reference the session skill's `tier: "session-summary"` hindsight entries for daily reporting
- File is discoverable and enabled in Hermes — no additional configuration needed
- User can start any session and the agent will follow the init→prompt→work→close lifecycle when `skill_view("session")` is loaded

---

## Self-Check: PASSED

- Created file verified: `[ -f ~/.hermes/skills/ngn-agent/session/SKILL.md ]` → FOUND (249 lines)
- All 14 decisions (D-01 through D-14) verified via grep — ALL PASS
- All 5 sections present — PASS
- All 7 procedure steps present — PASS
- No deferred ideas present — PASS
- Skill discoverable via `hermes skills list` — PASS
- No threat flags — PASS

---

*Phase: 07-main-session-skill*
*Completed: 2026-06-15*