ngn-agent/.planning/phases/07-main-session-skill/07-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
07-main-session-skill	01	execute	1		~/.hermes/skills/ngn-agent/session/SKILL.md	true	SKIL-04	truths artifacts key_links Agent detects similar previous sessions via hindsight_recall on session start and presents matches with resume/fresh option Agent creates a Jira Task ticket when user requests it, with configurable project and optional epic from cached list Agent searches and loads Confluence docs by ngn-agent tag when user requests it Agent prompts for Jira/Confluence updates at session end (user confirms before any mutation) Session summary is automatically saved to hindsight at session end (no prompt — unconditional per D-12) Future sessions can recall this session via hindsight_recall of the saved summary path provides min_lines ~/.hermes/skills/ngn-agent/session/SKILL.md Full session lifecycle orchestration instructions in Hermes SKILL.md format 180 from to via pattern session/SKILL.md Procedure Step 1 hindsight_recall tool Tool call instruction hindsight_recall from to via pattern session/SKILL.md Procedure Step 2 ngn-jira POST /rest/api/3/issue CLI command in Procedure ngn-jira.*POST.*issue from to via pattern session/SKILL.md Procedure Step 2b hindsight_retain (epic cache) Tool call for caching epics hindsight_retain.*epic from to via pattern session/SKILL.md Procedure Step 3 ngn-confluence GET /rest/api/search CLI command tagged search ngn-confluence.*tag from to via pattern session/SKILL.md Procedure Step 5 ngn-jira POST comment CLI command for comment ngn-jira.*comment from to via pattern session/SKILL.md Procedure Step 7 hindsight_retain tool (session summary) Unconditional tool call hindsight_retain.*session-summary

Create the main ngn-agent session orchestration skill — a Hermes SKILL.md file that guides the agent through the full session lifecycle: detect similar previous sessions, prompt for Jira ticket and Confluence docs, work, and update/save at session end.

Purpose: Replace the ad-hoc per-session workflow with a standardized, repeatable session lifecycle covering the initial-plan.md func session() workflow. Every session follows the same init→work→close pattern regardless of task.

Output: ~/.hermes/skills/ngn-agent/session/SKILL.md — one file, zero code/installs/config changes.

<execution_context> @/Users/bapung/.config/opencode/gsd-core/workflows/execute-plan.md @/Users/bapung/.config/opencode/gsd-core/templates/summary.md </execution_context>

# Containing Artifacts for This Phase

@/Users/bapung/.planning/ROADMAP.md @/Users/bapung/.planning/REQUIREMENTS.md @/Users/bapung/.planning/phases/07-main-session-skill/07-CONTEXT.md @/Users/bapung/.planning/phases/07-main-session-skill/07-RESEARCH.md @/Users/bapung/Razer/ngn-agent/initial-plan.md

Existing Skill Format References (4 patterns to follow)

@/Users/bapung/.hermes/skills/ngn-agent/aws-diagnostics/SKILL.md @/Users/bapung/.hermes/skills/ngn-agent/jira/SKILL.md @/Users/bapung/.hermes/skills/ngn-agent/confluence/SKILL.md @/Users/bapung/.hermes/skills/ngn-agent/bitbucket/SKILL.md

Task 1: Create session/SKILL.md with full session lifecycle procedure

<read_first> - 07-RESEARCH.md §"Example 1: session/SKILL.md (Full Content)" for the reference implementation - 07-CONTEXT.md for all locked decisions (D-01 through D-14) to embed in the skill - aws-diagnostics/SKILL.md, jira/SKILL.md, confluence/SKILL.md, bitbucket/SKILL.md for format fidelity - initial-plan.md for the original func session() workflow </read_first>

~/.hermes/skills/ngn-agent/session/SKILL.md Create the directory `~/.hermes/skills/ngn-agent/session/` and write `SKILL.md` with:

**Frontmatter (per D-14 + existing skill convention):**
- `name: session` (matching directory name for clean `skill_view("session")` discovery)
- `description: "Main ngn-agent session lifecycle — init, work, close"`
- `tags: [ngn-agent, platform-engineering, session]`
- `category: devops`, `requires_toolsets: [terminal]`
- `version: 1.0.0`

**Sections (follow exact existing skill structure):**

### When to Use
Broad trigger conditions: "Load this skill at the START of EVERY platform engineering session, before any other work. This skill defines the standard session workflow." Include specific trigger examples (infrastructure task, Jira ticket creation, Confluence doc lookup, session end wrap-up).

### Important
- "Keep this skill loaded for the entire session" — note about re-loading via `skill_view("session")` if evicted
- D-02: Never create Jira tickets without asking first
- D-11: Never update Confluence without asking first
- D-12: Always save session summary to hindsight at end (no prompt)
- D-08: User must confirm before any Jira mutation
- Repos already mounted at `/workspace/` from Phase 6

### Procedure (7 steps — map to D-01 through D-13)

**Step 1: Check for Similar Previous Sessions (D-01)**
- Call `hindsight_recall` with query describing user's task, budget low
- Present matches in format: "Found [N] similar sessions from the last 2 weeks: [Title — Date — snippet]"
- Ask: resume (load context) or start fresh (proceed to step 2)

**Step 2: Prompt for Jira Ticket Creation (D-02, D-05, D-06, D-07)**
- Ask user if they want a Task ticket
- If yes:
  1. Ask which Jira project
  2. Check hindsight for cached epics (`hindsight_recall` query "jira epics cached"). If cache >24h old or user says it's wrong, refresh via `ngn-jira GET` and save via `hindsight_retain` with `tier: "epic-cache"`
  3. Present cached epics, ask if user wants to set parent epic
  4. Create Task via `ngn-jira POST /rest/api/3/issue` with project, summary, issuetype "Task", optional parent
  5. Note the ticket key for session-end steps
- If no: proceed to step 3

**Step 3: Prompt for Confluence Docs (D-03, D-09, D-10)**
- Ask user if they want to load relevant docs
- If yes:
  1. Search by tag via `ngn-confluence GET /rest/api/search?cql=tag="ngn-agent"`
  2. Present matching pages (title, space, last modified)
  3. Ask which pages to load
  4. Load selected page content (expand=body.storage)
- If no: proceed to step 4

**Step 4: Work Phase (D-04)**
- Repos already mounted at `/workspace/` (rai-ops, rai-deployment, rai-devtools)
- Additional repo cloning: `git clone git@bitbucket.org:razersw/<repo>.git /workspace/<repo>`
- Session skill remains loaded for session-end steps

**Step 5: Session-End — Update Jira (D-08, D-12)**
- When user indicates work is complete: ask "Update Jira with summary comment?"
- If yes (and ticket exists): `ngn-jira POST /rest/api/3/issue/<KEY>/comment` with summary body
- Do NOT transition tickets without explicit user confirmation

**Step 6: Session-End — Update Confluence (D-11, D-12)**
- Ask "Create or update Confluence page documenting this session?"
- If yes: POST new page (with `labels: [{"name": "ngn-agent"}]`) or PUT update to existing
- If no: proceed

**Step 7: Save Session Summary to Hindsight (D-12, D-13)**
- **Automatic — no prompt.** Always save.
- Call `hindsight_retain` with `tier: "session-summary"` and structured content containing:
  - Date, Task description, Repos worked on, Jira ticket key (or "none")
  - Key Decisions, Outcomes, Next Steps

### Pitfalls (from RESEARCH.md)
Include all 6 pitfalls from the research: skill not loaded at start, epic cache too old, Confluence tag mismatch, Jira project 404, empty hindsight recall, long session eviction. Use the exact text from RESEARCH.md §Pitfalls.

### Verification (from RESEARCH.md)
Include the 6-point checklist matching the success criteria in must_haves.

**Formatting rules:**
- Code blocks inside Procedure MUST use triple-backtick with `bash` language tags for CLI commands, and plain text for hindsight tool calls
- Each numbered step should be a separate `### N. Title` heading
- Use bullet points for sub-steps, numbered lists for sequential actions
- The "Important" section must include the context-eviction reload note
- Do NOT include any deferred ideas (daily reporting, stale archive, auto-create Jira — these are Phase 8 and specifically deferred per DEF-01/02/03)
- The file must be >=180 lines to cover all decisions and procedures comprehensively

**Key content differences from the RESEARCH.md example (implement these corrections):**
1. Set `name: session` (not `ngn-agent-session`) in frontmatter — the directory name is `session/`, agent discovers as `ngn-agent/session`, so `skill_view("session")` is the expected call
2. Ensure D-08 is explicit: "Do NOT transition tickets (close/resolve) without explicit user confirmation" appears in Step 5
3. Add context-eviction reload reminder in the Important section and Pitfalls
4. Ensure the Step 7 hindsight_retain is clearly unconditional ("Do NOT ask the user — this step is automatic")

ls ~/.hermes/skills/ngn-agent/session/SKILL.md && wc -l ~/.hermes/skills/ngn-agent/session/SKILL.md - File exists at `~/.hermes/skills/ngn-agent/session/SKILL.md` - File is >=180 lines - Frontmatter contains all required fields (name, description, tags, category, requires_toolsets, version) - All 7 procedure steps present with correct headings - All sections present: When to Use, Important, Procedure, Pitfalls, Verification - Step 2 references epic cache with hindsight_retain tier epic-cache - Step 7 indicates automatic save (no user prompt) - Step 8 and 9 do not exist (phase only has 7 steps) Task 2: Verify skill discoverability, structure, and decision coverage

<read_first> - ~/.hermes/skills/ngn-agent/session/SKILL.md (just created in Task 1) - 07-CONTEXT.md (decisions D-01 through D-14 for coverage check) </read_first>

~/.hermes/skills/ngn-agent/session/SKILL.md Run the following verification sequence:

1. **Discoverability:** Run `hermes skills list` and confirm the session skill appears in the output. If `hermes` CLI is not available, use `ls ~/.hermes/skills/ngn-agent/session/SKILL.md` to confirm file placement matches the pattern of 4 existing skills.

2. **Structure verification:** Read the created SKILL.md and confirm:
   - YAML frontmatter is valid and contains: name, description, metadata.hermes.tags, metadata.hermes.category, metadata.hermes.requires_toolsets, version
   - Sections present: ## When to Use, ## Important, ## Procedure, ## Pitfalls, ## Verification
   - Procedure has exactly 7 numbered steps (### 1. through ### 7.)
   - Step 7 heading says "Save to Hindsight" or similar — confirms automatic save
   - All code blocks with CLI commands use ```bash language tag

3. **Decision coverage check:** grep the SKILL.md for each decision D-01 through D-14 to confirm it's implemented:
   - D-01 → "hindsight_recall" in Step 1
   - D-02 → "Would you like to create a Jira Task" in Step 2
   - D-03 → "ngn-agent" tag search in Step 3
   - D-04 → "Repos are already mounted" in Step 4
   - D-05 → "issuetype.*Task" in Step 2 Jira POST
   - D-06 → "Ask which Jira project" in Step 2
   - D-07 → "epic cache" or "epic" in Step 2
   - D-08 → "Do NOT transition" or "confirm" in Step 5
   - D-09 → "tag.*ngn-agent" in Step 3
   - D-10 → "which pages" or "user selects" in Step 3
   - D-11 → "without asking" or "confirm" in Step 6
   - D-12 → "no prompt" and "automatic" in Important or Step 7
   - D-13 → structured summary fields (Date, Task, Repos, Jira, Decisions, Outcomes) in Step 7
   - D-14 → frontmatter with name, description, tags, requires_toolsets

4. **Deferred ideas check:** grep for "daily report", "stale", "archive", "auto-create" — these MUST NOT appear in the skill content (they belong to Phase 8).

grep -q '### 7\.' ~/.hermes/skills/ngn-agent/session/SKILL.md && grep -q 'hindsight_recall' ~/.hermes/skills/ngn-agent/session/SKILL.md && grep -q 'hindsight_retain' ~/.hermes/skills/ngn-agent/session/SKILL.md && grep -q 'ngn-jira' ~/.hermes/skills/ngn-agent/session/SKILL.md && grep -q 'ngn-confluence' ~/.hermes/skills/ngn-agent/session/SKILL.md - SKILL.md is discoverable by Hermes (appears in `hermes skills list` or confirmed in correct directory) - All 14 decisions (D-01 through D-14) are implemented in the skill - No deferred ideas (daily reporting, stale archive, auto-create) appear in the skill - All 7 procedure steps are present and correctly ordered - All 5 sections are present (When to Use, Important, Procedure, Pitfalls, Verification)

<threat_model>

Trust Boundaries

Boundary	Description
Agent → Atlassian Cloud API	Jira/Confluence writes cross a network boundary to external SaaS. All mutations gated by user confirmation.
Agent → Hindsight local store	Session summary saves to local embedded PostgreSQL. Read-only recall unrestricted.

STRIDE Threat Register

Threat ID	Category	Component	Disposition	Mitigation Plan
T-07-01	Tampering	Jira ticket creation/update (ngn-jira POST)	mitigate	D-08: Procedure Step 5 explicitly instructs agent to ask user before any Jira mutation. Step 2 also requires user prompt before ticket creation. Skill language: "Never create Jira tickets without asking the user first" in Important section.
T-07-02	Tampering	Confluence page create/update (ngn-confluence POST/PUT)	mitigate	D-11: Procedure Step 6 explicitly instructs agent to ask user before any Confluence update. Skill language: "Never update Confluence without asking the user first" in Important section.
T-07-03	Information Disclosure	hindsight_retain session summary	mitigate	D-13: Summary format is structured, task-level information (repos, Jira ref, decisions, outcomes) — not raw conversation transcripts. Hindsight runs in local_embedded mode (local PostgreSQL). Skill does not instruct agent to retain raw conversation.
</threat_model>

1. File exists at `~/.hermes/skills/ngn-agent/session/SKILL.md` ✓ 2. All 14 decisions (D-01 through D-14) are implemented — verified by grep in Task 2 ✓ 3. No deferred ideas (daily reporting, stale archive, auto-create) are present ✓ 4. Format matches the 4 existing ngn-agent skills (frontmatter, sections, conventions) ✓ 5. Skill is discoverable by Hermes or confirmed at correct path ✓ 6. All code blocks use correct syntax (bash for CLI, plain text for tool calls) ✓

<success_criteria>

• Agent can discover and load the session skill via skill_view("session")
• When loaded, the skill guides the agent through the full init→prompt→work→close lifecycle
• At session start: hindsight_recall check for similar sessions (D-01), user prompted for Jira (D-02) and Confluence (D-03)
• At session end: user prompted for Jira update (D-08) and Confluence update (D-11), session summary auto-saved to hindsight (D-12/D-13)
• No write operation (Jira/Confluence) happens without user confirmation
• Epic cache managed in hindsight with refresh when stale (D-07) </success_criteria>

Create `.planning/phases/07-main-session-skill/07-01-SUMMARY.md` when done