From 5d7232ec310d15be384f583f65e6533feef861f2 Mon Sep 17 00:00:00 2001 From: Bagas Purwa Sentika Date: Mon, 15 Jun 2026 20:27:59 +0800 Subject: [PATCH] docs(07-main-session-skill): complete session skill plan - Created ~/.hermes/skills/ngn-agent/session/SKILL.md (249 lines) - 7-step session lifecycle: hindsight recall, Jira prompt, Confluence prompt, work, Jira update, Confluence update, automatic hindsight save - All 14 decisions D-01 through D-14 implemented - All threat mitigations (T-07-01, T-07-02, T-07-03) in place - Skill discoverable via hermes skills list as 'session' under 'ngn-agent' --- .../07-main-session-skill/07-01-SUMMARY.md | 144 ++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 .planning/phases/07-main-session-skill/07-01-SUMMARY.md diff --git a/.planning/phases/07-main-session-skill/07-01-SUMMARY.md b/.planning/phases/07-main-session-skill/07-01-SUMMARY.md new file mode 100644 index 0000000..c837c96 --- /dev/null +++ b/.planning/phases/07-main-session-skill/07-01-SUMMARY.md @@ -0,0 +1,144 @@ +--- +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*