# Phase 7: Main Session Skill - Context

**Gathered:** 2026-06-14
**Status:** Ready for planning

<domain>
## Phase Boundary

Create the main ngn-agent session orchestration SKILL.md — a Hermes skill that guides the agent through the session lifecycle: detect similar previous sessions, set up workspace, create Jira ticket, load Confluence docs, work, and update at session end.

**In scope:** Hermes SKILL.md file in `~/.hermes/skills/ngn-agent/`, session start/end workflow procedures, hindsight integration for similarity search and session saves, Jira ticket creation prompt, Confluence doc search by tag, on-demand epic cache

**Out of scope:** Cron reporting (Phase 8), stale session archive (Phase 8), on-demand repo cloning (already works from Phase 6), AWS diagnostics (existing skill), Bitbucket PR review (existing skill)
</domain>

<decisions>
## Implementation Decisions

### Session Start Behavior
- **D-01:** On session start, automatically check hindsight for similar sessions from the last 2 weeks. Present any matches to the user with option to resume or start fresh.
- **D-02:** Jira ticket creation is **always prompted** — create a Task type. The user decides whether to create one each session.
- **D-03:** Confluence doc loading is **always prompted** — when user wants docs, search by a dedicated ngn-agent tag.
- **D-04:** After prompting, load workspace (DEFAULT_REPOS already mounted via Phase 6), then proceed to work.

### Jira Integration
- **D-05:** Always create issue type `Task` for session tickets.
- **D-06:** Default Jira project/board is configurable — no hardcoded project. The agent asks which project when creating.
- **D-07:** Query available epics from Jira and cache them in hindsight long-term memory. Refresh the cache only occasionally or when the user explicitly asks. The agent should present cached epics when creating a ticket so the user can optionally set the parent epic.
- **D-08:** The user must confirm before any Jira update (comment, transition, etc.).

### Confluence Integration
- **D-09:** Create a dedicated tag for ngn-agent session documentation (e.g., `ngn-agent` or `platform-engineering`). All session-related Confluence pages use this tag.
- **D-10:** When the user wants to load docs, search Confluence by this tag and present matching pages. The user selects which to load.
- **D-11:** The user must confirm before any Confluence update.

### Session-End Behavior
- **D-12:** At session end (when user indicates work is complete or session wraps up):
  - Prompt: "Update Jira?" — if yes, add summary comment
  - Prompt: "Update Confluence?" — if yes, create/update doc
  - **Always save session summary to hindsight memory** (no prompt — automatic)
- **D-13:** Session summary saved to hindsight includes: task description, repos worked on, Jira ticket reference (if created), key decisions, outcomes.

### Skill Format
- **D-14:** Hermes SKILL.md format — one file at `~/.hermes/skills/ngn-agent/session/SKILL.md` (following the existing skill convention). Standard frontmatter with `name`, `description`, `tags`, `requires_toolsets`.

### the agent's Discration
- **Tag name for Confluence**: `ngn-agent` is the default, but planner can pick something more specific if needed
- **Epic cache refresh strategy**: Refresh every 24h or on explicit user request — planner can define the exact mechanism
- **Similar session display format**: How many to show, what info to include (title, date, summary snippet)
</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Existing Skills (Reference Format)
- `~/.hermes/skills/ngn-agent/aws-diagnostics/SKILL.md` — Reference for SKILL.md format (frontmatter, procedure, when to use)
- `~/.hermes/skills/ngn-agent/jira/SKILL.md` — Jira query skill (will be referenced by session skill)
- `~/.hermes/skills/ngn-agent/confluence/SKILL.md` — Confluence search skill (will be referenced by session skill)

### Completed Phases (Dependencies)
- `.planning/phases/05-hindsight-memory-provider/05-01-SUMMARY.md` — Hindsight active with `hindsight_recall`, `hindsight_retain`, `hindsight_reflect` tools
- `.planning/phases/06-default-repos-ssh-mount/06-01-SUMMARY.md` — DEFAULT_REPOS mounted at `/workspace/rai-*`, SSH keys active

### Project Documents
- `initial-plan.md` — Original session workflow specification (functions `session()`, `daily_report()`, `daily_cleanup()`)
- `.planning/REQUIREMENTS.md` §SKIL-04 — Requirement definition
- `.planning/ROADMAP.md` §Phase 7 — Phase goal and success criteria

### Hermes Configuration
- `~/.hermes/config.yaml` §`memory.provider: hindsight` — Active memory provider for recall/save
- `~/.hermes/.env` — JIRA_EMAIL, JIRA_API_TOKEN, DEFAULT_REPOS env vars
</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- **Existing skill format**: 4 SKILL.md files in `~/.hermes/skills/ngn-agent/` — use same frontmatter conventions, procedure format, and "When to Use" / "Pitfalls" sections
- **Hindsight tools**: `hindsight_recall` for similar session search, `hindsight_retain` for session summary save, `hindsight_reflect` for cross-session synthesis
- **Atlassian scripts**: `ngn-jira`, `ngn-confluence`, `ngn-bitbucket` at `~/.hermes/scripts/` mounted to `/usr/local/bin:ro` in Docker

### Established Patterns
- **SKILL.md structure**: name/description frontmatter → When to Use → Important → Procedure → Pitfalls → Verification
- **Script invocation**: Skills use `ngn-*` scripts via terminal commands inside Docker

### Integration Points
- `~/.hermes/skills/ngn-agent/session/SKILL.md` — New skill file (create)
- `~/.hermes/skills/ngn-agent/jira/SKILL.md` — Referenced for Jira operations
- `~/.hermes/skills/ngn-agent/confluence/SKILL.md` — Referenced for Confluence operations
- Hindsight memory — Used for similar session recall and session summary save
</code_context>

<specifics>
## Specific Ideas

- The session skill should be the "entrypoint" skill that the agent loads when starting work on a platform engineering task
- Similar session check should be lightweight — quick hindsight_recall query, not a deep search
- The workflow mirrors `initial-plan.md`'s `func session()` — implement each step as a section in the skill procedure
</specifics>

<deferred>
## Deferred Ideas

- Daily reporting cron (Phase 8)
- Stale session archive (Phase 8)
- Auto-create Jira tickets without prompt — deferred, user wants manual control
</deferred>

---

*Phase: 7-Main Session Skill*
*Context gathered: 2026-06-14*