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

Phase 7: Main Session Skill - Context

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

## 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)

## 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)

<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>

## 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

## Deferred Ideas

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

---

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