bapung/ngn-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d494b274d92b407d7b529d3bfae8cfc0309de8d8
ngn-agent/.planning/phases/07-main-session-skill/07-RESEARCH.md

50 KiB
Raw Blame History

Phase 7: Main Session Skill — Research

Researched: 2026-06-15 Domain: Hermes Session Orchestration Skill (SKILL.md) Confidence: HIGH

Summary

Phase 7 creates the main ngn-agent session orchestration SKILL.md at ~/.hermes/skills/ngn-agent/session/SKILL.md — a Hermes skill that guides the agent through the full session lifecycle defined in initial-plan.md: detect similar previous sessions, set up workspace, create Jira ticket, load Confluence docs, work, and update at session end.

What this phase DOES NOT do: It does not write any Python code, install any packages, modify any Hermes config, or change the Docker setup. It is purely a SKILL.md authoring phase — one markdown file with YAML frontmatter and structured procedure sections.

How it works: The session skill follows the standard Hermes progressive disclosure pattern. The agent loads it via skill_view("ngn-agent/session") when the "When to Use" conditions match (user starts a platform engineering task). The session skill's Procedure section then guides the agent through:

  1. Session Start: Use hindsight_recall to find similar sessions → present to user
  2. Jira Prompt: Ask user if they want a ticket → create Task via ngn-jira POST → optionally set epic from cached list
  3. Confluence Prompt: Ask user if they want docs → search by tag via ngn-confluence GET
  4. (Work Phase): Repos already mounted (Phase 6), agent works normally
  5. Session End: Prompt Jira update → prompt Confluence update → auto hindsight_retain session summary

Cross-skill orchestration is handled by the session skill instructing the agent to use ngn-jira and ngn-confluence CLI scripts directly (these are mounted into Docker). For skills already installed (jira-query, confluence-search), the session procedure tells the agent to load them via skill_view("jira-query") when needed.

Primary recommendation: Create a single SKILL.md following the exact same frontmatter and section conventions as the 4 existing ngn-agent skills (aws-diagnostics, bitbucket, jira, confluence). The skill structure is: YAML frontmatter → ## When to Use → ## Important → ## Procedure (numbered steps) → ## Pitfalls → ## Verification.

Estimated effort: ~30 minutes for SKILL.md creation and verification — one file, no installs, no config changes.

User Constraints (from CONTEXT.md)

Locked Decisions

  • 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.
  • 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.).
  • 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.
  • 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.
  • 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 Discretion

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

Deferred Ideas (OUT OF SCOPE)

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

Phase Requirements

ID Description Research Support
SKIL-04 Main ngn-agent session orchestration skill covering the initial-plan.md workflow — detect similar prev sessions (via hindsight), load DEFAULT_REPOS, create Jira ticket per session, load Confluence docs, update docs/Jira at session end All skill patterns, cross-skill orchestration, hindsight_recall/retain usage, and Jira/Confluence scripting documented below. Single-file SKILL.md at ~/.hermes/skills/ngn-agent/session/SKILL.md.

Architectural Responsibility Map

Capability Primary Tier Secondary Tier Rationale
Session workflow orchestration Hermes skill system (SKILL.md) — Skill defines procedure; agent follows instructions. No plugin code needed.
Similar session detection Agent (LLM + hindsight_recall) — Skill instructs agent to call hindsight_recall with task description query. Agent interprets results and presents to user.
Jira ticket creation Container (ngn-jira script) — ngn-jira script mounted in Docker; skill provides the exact POST call. No Python plugin needed.
Confluence doc search Container (ngn-confluence script) — ngn-confluence script mounted in Docker; skill provides the exact GET call.
Epic cache in hindsight Hindsight memory Agent (periodic refresh) D-07: Epics queried from Jira, saved via hindsight_retain as long-term memory. Agent checks cache age and refreshes when stale.
Session summary persistence Hindsight memory (hindsight_retain) — D-12: Auto-save at session end via hindsight_retain with structured summary. No prompt.
User prompting (Jira/Confluence) Agent (in-skill orchestration) — The Procedure section instructs the agent to ask the user before any action. Standard skill pattern.
Cross-skill loading Agent (skill_view) — Session skill tells agent to load jira-query and confluence-search skills when needed via skill_view("jira-query").

Standard Stack

Core

No new libraries or packages. This phase creates one SKILL.md file:

Component Version Purpose Why Standard
Hermes SKILL.md format — Session lifecycle orchestration instructions All 4 existing ngn-agent skills use this format. Hermes official docs define the structure. [VERIFIED: hermes docs + 4 existing skills]
hindsight_recall tool — Similar session detection on session start Active via Phase 5 Hindsight setup in hybrid memory_mode. [VERIFIED: Phase 5 SUMMARY]
hindsight_retain tool — Save session summary at session end Same source — Hindsight hybrid mode provides 3 tools. [VERIFIED: Phase 5 SUMMARY]
ngn-jira script — Jira ticket creation and update Mounted at /usr/local/bin/ngn-jira inside Docker. [VERIFIED: existing skills + Phase 6 SUMMARY]
ngn-confluence script — Confluence search and page operations Mounted at /usr/local/bin/ngn-confluence inside Docker. [VERIFIED: existing skills + Phase 6 SUMMARY]
skill_view tool — Load jira-query/confluence-search skills when needed Standard Hermes progressive disclosure mechanism. [VERIFIED: Hermes docs §Skills System]

Supporting

Component Purpose When to Use
skills_list() Agent discovers session and other skills On session start, agent checks available skills
hermes bundles create Group session + jira + confluence under one command If user wants /session as a one-shot entry point
skill_manage tool Agent-created skill updates Not needed for Phase 7 — skill is hand-authored

Alternatives Considered

Instead of Could Use Tradeoff
Single session SKILL.md Hermes plugin with on_session_start hook Plugin requires Python code, plugin.yaml, and register(ctx) function. SKILL.md is simpler, zero code, no install. But plugin hooks guarantee execution on session start; skill depends on agent deciding to load it.
Skill bundle (session + jira + confluence) Individual skill_view calls within session procedure Bundle loads all skills at once, increasing token usage for skills that may not be needed. Sequential skill_view calls are more token-efficient.
Direct ngn-jira/ngn-confluence commands Loading jira-query/confluence-search skills via skill_view Both approaches work. Direct commands are simpler and more explicit. Loading skills via skill_view adds context about how to use the APIs including pitfalls. Prefer skill_view for richer context.

Installation: No packages to install. One SKILL.md file created on disk.

Package Legitimacy Audit

No packages are installed in this phase. This is a single SKILL.md file creation — no npm, pip, or cargo dependencies.

Package Registry Verdict Disposition
— — — No packages to verify

Architecture Patterns

System Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                     Hermes Agent (LLM)                                   │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │              skill_view("ngn-agent/session")                      │   │
│  │              ───────────────────────────────                      │   │
│  │              Session SKILL.md loaded into context                 │   │
│  └────────────────────────────────┬─────────────────────────────────┘   │
│                                   │                                      │
│           ┌───────────────────────┼───────────────────────┐              │
│           │                       │                       │              │
│           ▼                       ▼                       ▼              │
│  ┌─────────────────┐   ┌─────────────────┐   ┌──────────────────────┐   │
│  │ SKILL_VIEW      │   │ HINDSIGHT_TOOLS │   │ JIRA/CONFLUENCE      │   │
│  │ cross-skill     │   │ recall/retain   │   │ ngn-jira/ngn-        │   │
│  │ loading         │   │                 │   │ confluence scripts   │   │
│  │                 │   │                 │   │                      │   │
│  │ skill_view(     │   │ hindsight_recall│   │ ngn-jira GET/POST    │   │
│  │  "jira-query")  │   │ hindsight_retain│   │ ngn-confluence GET   │   │
│  │ skill_view(     │   │                 │   │ ngn-confluence PUT   │   │
│  │  "confluence-   │   │                 │   │                      │   │
│  │   search")      │   │                 │   │                      │   │
│  └─────────────────┘   └─────────────────┘   └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
         │                        │                        │
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
│ Existing Skills │   │ Hindsight Local      │   │ Atlassian Cloud      │
│ ~/.hermes/      │   │ Embedded Daemon      │   │ (via Docker scripts) │
│ skills/ngn-agent/│   │ (PostgreSQL KG)     │   │                      │
│                 │   │                      │   │ Jira REST API        │
│ jira-query      │   │ Session KG:          │   │ Confluence REST API  │
│ confluence-     │   │ - similar sessions   │   │                      │
│   search        │   │ - epic cache         │   │                      │
│                 │   │ - session summaries  │   │                      │
│ aws-diagnostics │   │                      │   │                      │
│ bitbucket-pr    │   │                      │   │                      │
└─────────────────┘   └──────────────────────┘   └──────────────────────┘

Data flow through the session lifecycle:

User: "I need to work on the CI/CD pipeline"

  1. Agent loads session skill via skill_view("ngn-agent/session")
     → Session SKILL.md instructions enter context

  2. [SESSION START] hindsight_recall(query="CI/CD pipeline work")
     → Returns similar sessions from last 2 weeks
     → Agent presents to user: "Found session 'Pipeline fixes' from 2 days ago — resume or start fresh?"

  3. [JIRA PROMPT] Agent asks: "Create a Jira Task ticket for this session?"
     → If yes: agent asks for project, shows cached epics (from hindsight), creates via ngn-jira POST
     → If no: continues without ticket

  4. [CONFLUENCE PROMPT] Agent asks: "Load Confluence docs tagged 'ngn-agent'?"
     → If yes: ngn-confluence GET search by tag, present pages, user selects
     → If no: continues without docs

  5. [WORK PHASE] Agent works on task using mounted repos (Phase 6)
     → Normal Hermes operation
     → (Session skill stays loaded for end-of-session steps)

  6. [SESSION END] User says "I'm done" or session wraps up
     → Agent: "Update Jira with a summary comment?"
     → Agent: "Update Confluence documentation?"
     → AUTO: hindsight_retain(structured summary)

Recommended Project Structure

~/.hermes/skills/ngn-agent/
├── aws-diagnostics/
│   └── SKILL.md               (existing — unchanged)
├── bitbucket/
│   └── SKILL.md               (existing — unchanged)
├── confluence/
│   └── SKILL.md               (existing — unchanged)
├── jira/
│   └── SKILL.md               (existing — unchanged)
└── session/
    └── SKILL.md               ★ NEW — main session orchestration skill

Only the session/SKILL.md file is new. Everything else already exists from v1.0.

Pattern 1: Hermes SKILL.md Format (from 4 existing ngn-agent skills)

What: All 4 existing ngn-agent skills follow an identical structure. The session skill MUST use the same format.

When to use: Every custom skill in the ngn-agent ecosystem.

---
name: <hyphenated-name>
description: <one-line description>
metadata:
  hermes:
    tags: [<keywords>]
    category: devops
    requires_toolsets: [terminal]
version: 1.0.0
---
# <Skill Title>

## When to Use
<conditions that trigger loading this skill>

## Important
<key rules, non-obvious constraints, safety notes>

## Procedure
### 1. <Step title>
<instructions, command templates, decision points>

### 2. <Step title>
<instructions>

## Pitfalls
- <known failure modes and how to avoid them>

## Verification
<how to confirm the skill executed correctly>

Source: [VERIFIED: 4 existing ngn-agent SKILL.md files at ~/.hermes/skills/ngn-agent/*/SKILL.md — all follow identical structure.] [VERIFIED: Hermes official docs §Skills System — confirms SKILL.md format with frontmatter fields.]

Pattern 2: Cross-Skill Orchestration within a Procedure

What: A skill's procedure can instruct the agent to load another skill, use a CLI script directly, or use a Hermes tool. The session skill uses all three patterns.

When to use: When one skill's workflow depends on capabilities provided by other skills (e.g., session workflow needs Jira ticket creation and Confluence search).

Pattern 2a — Load another skill via skill_view: The Procedure says: "Load the jira-query skill by calling skill_view("jira-query")." The agent then loads the full Jira skill content into context for detailed API guidance. This is useful for complex operations with multiple API endpoints.

Pattern 2b — Direct CLI invocation: The Procedure provides the exact command to run, referencing scripts the agent has access to in Docker. This is simpler and more explicit for well-known operations.

# Direct approach (more explicit):
ngn-jira POST '/rest/api/3/issue' --body '{...}'

# Skill-loading approach (more context):
skill_view("jira-query")
# Then use the commands from that skill

Recommendation: Use direct CLI commands for well-known operations (create ticket = POST to /rest/api/3/issue). Use skill_view for exploratory or multi-endpoint operations where the agent needs full API context.

Source: [VERIFIED: Hermes docs §Skills System — skill_view is the standard tool for loading skill content.] [VERIFIED: 4 existing ngn-agent skills all use direct CLI commands for their procedures — no cross-skill references among them (they're independent). The session skill is the first to need orchestration.]

Pattern 3: Skill-Borne User Prompts

What: A Hermes skill's Procedure section can instruct the agent to ask the user questions interactively. This is a standard pattern — the agent follows the skill's instructions and, at decision points, messages the user for input.

When to use: Any skill that requires user decisions at runtime (e.g., "which project?", "which epic?", "create Jira ticket?").

How it looks in the procedure:

### 2. Create Jira Ticket (Prompt)
Ask the user: "Would you like to create a Jira Task ticket for this session?"
- If YES: ...
- If NO: ...

Source: [VERIFIED: This is how standard Hermes skills work — the agent follows the procedure literally, including asking questions. The 4 existing ngn-agent skills don't have user prompts (they're query-only), but this is standard LLM tool-use behavior.]

Pattern 4: Hindsight Similarity Search via hindsight_recall

What: The session skill instructs the agent to call hindsight_recall with a query describing the current task. Hindsight returns relevant memories from past sessions. The agent presents these to the user.

When to use: At session start (D-01) — check for similar sessions from the last 2 weeks.

# In the procedure:
### 1. Check for Similar Sessions
Use the `hindsight_recall` tool with a query describing the current task
to find similar sessions from the last 2 weeks.

Parse the results for session references. Present to the user in this format:
  "Found X similar sessions from the last 2 weeks:"
  - [Session Title] — [Date] — [Summary snippet]
  Ask: "Would you like to resume any of these or start fresh?"

Key insight: Hindsight's recall_types: observation (set in Phase 5) means recall returns consolidated knowledge, not raw conversation turns. Session summaries saved via hindsight_retain with structured fields will be returned as observations, making them easy to identify as "previous sessions."

Source: [VERIFIED: Phase 5 hindsight config has memory_mode: hybrid — all 3 hindsight tools available. hindsight_recall queries the KG for semantically similar content.]

Pattern 5: Session Summary via hindsight_retain

What: At session end (D-12), the skill instructs the agent to call hindsight_retain with a structured summary containing task description, repos worked on, Jira ticket reference, key decisions, and outcomes.

When to use: On every session end — automatic, no prompt (D-12).

Recommended format for the summary:

hindsight_retain(tier="session-summary", content="
Session Summary
===============
Date: 2026-06-15
Task: Fix broken CI/CD pipeline for rai-deployment
Repos: rai-deployment, rai-ops
Jira: PLATFORM-123
Key Decisions:
- Switched CI runner from GitHub Actions to self-hosted
- Added timeout of 30 min for deployment jobs
Outcomes:
- CI/CD pipeline fixed and verified with 3 test runs
- Dockerfile cache layer optimized (build time reduced from 8m to 3m)
")

Format considerations: The summary should be structured text (not JSON) — Hindsight processes natural language observations best. Include all 5 fields from D-13. The tier="session-summary" helps differentiate from other memory types during recall queries.

Source: [VERIFIED: Phase 5 SUMMARY confirms hindsight_retain tool is available in hybrid mode. D-12 and D-13 define the save behavior and content.]

Anti-Patterns to Avoid

  • Hardcoding Jira project name: D-06 says configurable. The skill should instruct the agent to ASK the user which project, not hardcode.
  • Loading all skills upfront (bundle approach): Loading jira-query AND confluence-search AND session at the same start wastes tokens. Load them sequentially only when needed.
  • Auto-creating Jira tickets without prompt: D-02 says always prompt. The skill must explicitly instruct the agent to ask first.
  • Forgetting to mention the ngn-agent Confluence tag: D-09 creates a dedicated tag. The skill must reference this tag in the Confluence search step.
  • Skipping the hindsight save: D-12 specifies auto-save (no prompt). The skill must NOT have a user prompt for the save step — it should be unconditional.

Don't Hand-Roll

Problem Don't Build Use Instead Why
Session workflow execution Custom Python plugin with hooks Hermes SKILL.md SKILL.md is declarative, zero-code, follows progressive disclosure. Agent loads it naturally via skill_view().
Cross-skill orchestration Custom tool that combines skills Skill procedure with skill_view() calls Agent already has skill_view tool. Telling the agent to load another skill from within a procedure is the standard pattern.
User prompting system Custom input collection mechanism Inline agent questions The agent naturally asks users questions as part of conversation. The skill just says "Ask the user..." and the agent does it.
Session similarity detection Custom Python vector search hindsight_recall tool Hindsight already has semantic search with KG, entity resolution, and cross-session recall. Using it within the skill is zero additional code.

Key insight: The session skill is pure instruction — it doesn't need any code. The agent already has all the tools it needs (hindsight_recall, hindsight_retain, ngn-jira, ngn-confluence, skill_view). The SKILL.md just tells the agent when and how to use them in sequence.

Runtime State Inventory

Not applicable — this is a greenfield SKILL.md creation phase. No existing runtime state references old names, keys, or paths.

Category Items Found Action Required
Stored data None —
Live service config None —
OS-registered state None —
Secrets/env vars None —
Build artifacts None —

Nothing found: This phase creates one new file (session/SKILL.md). No rename, refactor, or migration involved.

Common Pitfalls

Pitfall 1: Session Skill Not Auto-Loaded by Agent

What goes wrong: The agent starts a platform engineering task without loading the session skill, so the session workflow (hindsight check, Jira prompt, Confluence prompt) is skipped entirely.

Why it happens: Skills follow progressive disclosure. The agent uses skills_list() to see all available skills, then decides which to load via skill_view(). If the agent doesn't recognize the "When to Use" conditions apply, it won't load the skill. Unlike plugin hooks (which fire automatically), skills require the agent's judgment.

How to avoid:

  • Make the "When to Use" section broad and explicit: "Load this skill at the START of EVERY platform engineering session, before any other work. This skill defines the standard session workflow."
  • Include trigger examples in "When to Use": "When the user says they want to work on infrastructure, or when you start a new platform engineering task, or when you need to create a Jira ticket or find Confluence docs."
  • Consider adding the skill name in the Hermes config's skills.always_include if such a setting exists, or instruct the user to start sessions with /session to force-load it.

Warning signs: Agent starts working on repos directly without asking about Jira tickets or Confluence docs. No hindsight check at start.

Pitfall 2: Agent Doesn't Load Dependent Skills When Instructed

What goes wrong: The session procedure says "Load the jira-query skill" but the agent either ignores the instruction or tries to use tools it doesn't have.

Why it happens: The agent may have a loaded stale skill list. Or the agent might try to use a tool (like ngn-jira POST) without first loading the skill that documents the API.

How to avoid: Include the exact tool call in the procedure: "Call skill_view("jira-query") to load the Jira skill. Then use the ngn-jira command documented there." Be explicit about the skill name — the agent will try to match it with a skill name from skills_list().

Warning signs: Agent says "I don't have access to a Jira tool" or tries to use an incorrect command.

Pitfall 3: Epic Cache Becomes Stale

What goes wrong: The epic list cached in hindsight shows old/closed epics, and the agent doesn't realize it's stale.

Why it happens: D-07 says "refresh only occasionally." Without a clear refresh strategy, the cache stays stale indefinitely.

How to avoid: The Procedure should include a step: "Check the age of the cached epic list. If it's more than 24 hours old, or if the user says the list looks wrong, query Jira for current epics and update the cache via hindsight_retain with a fresh list."

Warning signs: User says "that epic was closed last month" or "I don't see the current sprint's epics."

Pitfall 4: Hindsight_retain Session Summary Conflicts with Auto-Retain

What goes wrong: Hindsight's auto_retain: true (Phase 5, D-10) already saves conversation turns every 5 turns. The session summary saved via hindsight_retain at session end may duplicate information or conflict with auto-saved observations.

Why it happens: Two retention mechanisms operate independently: auto_retain creates observations from conversation turns; the skill instructs the agent to manually retain a structured summary at session end.

How to avoid: Design the session summary to be a higher-level, consolidated view — not a duplicate of individual observations. Include data that auto-retain wouldn't capture (Jira ticket number, key decisions summary, outcome assessment). Use a distinct tier="session-summary" to differentiate from auto-saved observations.

Warning signs: hindsight_recall returns very similar results from both session summaries and observations.

Pitfall 5: Skill Not Re-loaded for Session-End Steps

What goes wrong: The session-end steps (Jira/Confluence update prompts, hindsight_retain) are skipped because the agent no longer has the session skill loaded in context.

Why it happens: Skills are loaded once. If the session is long (many conversation turns), the skill content may be evicted from context by newer messages. The agent can't follow instructions it no longer has.

How to avoid: Include a note in the "Important" section: "Keep this skill loaded for the entire session. If context becomes too large, re-load this skill with skill_view("ngn-agent/session") before the session-end steps." Or make the session-end steps prominent enough that the agent checks back.

Warning signs: Agent completes work and waits for next instruction without offering to update Jira/Confluence or save to hindsight.

Code Examples

Example 1: session/SKILL.md (Full Content)

---
name: ngn-agent-session
description: Main ngn-agent session lifecycle — init, work, close
metadata:
  hermes:
    tags: [ngn-agent, platform-engineering, session]
    category: devops
    requires_toolsets: [terminal]
version: 1.0.0
---
# ngn-agent Session Lifecycle

## When to Use
When the user starts any platform engineering task or indicates they want to begin work. Load this skill at the START of every session before any other work. This is the standard session workflow for ngn-agent.

Also use when ending a session — the session-end steps ensure work is documented and saved.

## Important
- **Keep this skill loaded for the entire session** — if context grows large, reload via `skill_view("ngn-agent-session")`
- Never create Jira tickets without asking the user first
- Never update Confluence without asking the user first
- Always save session summary to hindsight at end (no user prompt for this step)
- Repos are already mounted at `/workspace/` from session start (Phase 6)

## Procedure

### 1. Check for Similar Previous Sessions
At the very start of a session, use `hindsight_recall` with a query describing the user's current task to find similar sessions from the last 2 weeks.

Example hindsight_recall call:

Tool: hindsight_recall Query: "<user's task description>" Budget: low


Present any matches to the user in this format:

Found [N] similar sessions from the last 2 weeks:

  1. [Session Title] — [Date] — [one-line summary]
  2. [Session Title] — [Date] — [one-line summary]

Ask the user: "Would you like to resume any of these sessions, or start fresh?"
- If they choose to resume: load that session's context and continue
- If they choose fresh: proceed to step 2

### 2. Prompt: Create Jira Ticket
Ask the user: "Would you like to create a Jira Task ticket for this session?"
- If YES:
  1. Ask which Jira project to use (e.g., "PLATFORM", "DEVOPS")
  2. Check hindsight for cached epics:
     ```
     Tool: hindsight_recall
     Query: "jira epics cached"
     ```
  3. Present cached epics to the user: "Available epics: [list]. Would you like to set a parent epic?"
     - If the cache is >24h old OR user says it looks wrong, refresh:
       ```
       ngn-jira GET '/rest/api/3/search?jql=issuetype=Epic AND project=<PROJECT>&fields=summary,id&maxResults=50'
       ```
       Save fresh epics to hindsight:
       ```
       Tool: hindsight_retain
         tier: "epic-cache"
         content: "Jira Epic Cache [date]: [project]: [list of epic key + summary]"
       ```
     - If epic cache is fresh (less than 24h), use the cached list
  4. Create the Task:
     ```
     ngn-jira POST '/rest/api/3/issue' --body '{
       "fields": {
         "project": {"key": "<PROJECT>"},
         "summary": "<session task description>",
         "issuetype": {"name": "Task"},
         "parent": {"key": "<EPIC_KEY>"}  // optional, if user selected an epic
       }
     }'
     ```
  5. Save the ticket key (e.g., `PLATFORM-123`) for use in session-end steps
- If NO: proceed to step 3 (no Jira ticket this session)

### 3. Prompt: Load Confluence Documentation
Ask the user: "Would you like to load relevant Confluence documentation?"
- If YES:
  1. Search by the ngn-agent tag:
     ```
     ngn-confluence GET '/rest/api/search?cql=tag="ngn-agent"&limit=20'
     ```
  2. Present matching pages to the user: "Found [N] pages tagged 'ngn-agent':"
     - [Title] — [space] — [last modified date]
  3. Ask: "Which pages would you like me to load?"
  4. For each selected page, load its content:
     ```
     ngn-confluence GET '/rest/api/content/{pageId}?expand=body.storage'
     ```
- If NO: proceed to step 4

### 4. Work Phase
Repos are already mounted at `/workspace/` (rai-ops, rai-deployment, rai-devtools). Proceed with the task using standard Hermes tools.

If you need to clone additional repos:

git clone git@bitbucket.org:razersw/.git /workspace/


The session skill remains loaded for the session-end steps below.

### 5. Session-End: Update Jira
When the user indicates work is complete or the session wraps up:
Ask the user: "Would you like me to update the Jira ticket with a summary comment?"
- If YES (and a ticket was created in step 2):

ngn-jira POST '/rest/api/3/issue//comment' --body '{ "body": "<summary of work done, key decisions, next steps>" }'

- If NO: proceed without updating Jira

Note: Do NOT transition tickets (e.g., close/resolve) without explicit user confirmation (D-08).

### 6. Session-End: Update Confluence
Ask the user: "Would you like me to create or update a Confluence page documenting this session?"
- If YES:
- If this is a new page:
  ```
  ngn-confluence POST '/rest/api/content' --body '{
    "type": "page",
    "title": "<Session Date>: <Task Description>",
    "space": {"key": "<SPACE_KEY>"},
    "body": {
      "storage": {
        "value": "<h1>Session Summary</h1><p>...</p>",
        "representation": "storage"
      }
    },
    "metadata": {
      "properties": {
        "content-appearance": {"value": "page"}
      }
    },
    "labels": [{"name": "ngn-agent"}]
  }'
  ```
- If updating an existing page: ask which page, then PUT to update
- If NO: proceed without updating Confluence

### 7. Session-End: Save to Hindsight (Automatic — No Prompt)
ALWAYS save a session summary to hindsight memory. Do NOT ask the user — this step is automatic.

Tool: hindsight_retain tier: "session-summary" content: " Session Summary

Date: Task: Repos: Jira: <ticket key or "none"> Key Decisions:

  • <decision 1>
  • <decision 2> Outcomes:
  • <outcome 1>
  • <outcome 2> Next Steps:
  • <next step 1> "

This summary allows future `hindsight_recall` queries to find this session for similarity matching.

## Pitfalls

- **Skill not loaded at session start:** If you reach step 2 without doing step 1 (hindsight check), execute step 1 retroactively or ask the user if they want to check for similar sessions now
- **Epic cache too old:** Epics may change between sessions. Check the cache timestamp and refresh if >24h old
- **Confluence tag mismatch:** If the `ngn-agent` tag returns no results, try `platform-engineering` as fallback, or ask the user what tag they use
- **Jira project doesn't exist:** If the create ticket call fails with 404, the project key may be wrong — ask the user to confirm
- **Hindsight recall returns nothing:** The first few sessions may have no matches. That's normal — proceed with fresh session
- **Long sessions may evict this skill:** If context becomes large, reload with `skill_view("ngn-agent-session")` before steps 5-7

## Verification

1. On session start, agent checks for similar sessions ✓
2. Jira ticket created (or user declined) ✓
3. Confluence docs loaded (or user declined) ✓
4. At session end, user prompted for Jira/Confluence updates ✓
5. Session summary saved to hindsight ✓
6. Future sessions can recall this session via hindsight_recall ✓

Note: The skill above uses ngn-agent-session as the name field. The actual skill name should match what's used in the directory. Since the skill will live at ~/.hermes/skills/ngn-agent/session/SKILL.md, the agent might discover it as ngn-agent/session (directory path) or as the name field. Use name: ngn-agent-session for a clean identifier.

Source: [VERIFIED: Existing ngn-agent skills use the same SKILL.md structure. Hermes official docs confirm all frontmatter fields and section conventions.]

Example 2: Cross-Skill Loading from Procedure

When the session procedure wants the agent to use the Jira skill's detailed guidance for a complex operation:

### 2a. Create Jira Ticket
Before creating the ticket, load the jira-query skill for detailed API reference:
1. Call `skill_view("jira-query")`
2. Review the procedure for creating issues
3. Use `ngn-jira POST '/rest/api/3/issue'` with the correct field structure

The agent loads the full jira-query skill content into context, gaining access to its procedure, pitfalls, and environment variable requirements.

Example 3: Hindsight Epic Cache Management

Pattern for caching and refreshing epics:

### 2b. Epic Selection (if user wants to set parent)
1. Call `hindsight_recall` with query "epic cache" and budget "low"
2. If results contain a cached epic list:
   - Parse the cache timestamp from the content
   - If timestamp is >24h old, refresh: query Jira for current epics and `hindsight_retain` the updated list
   - If fresh, present the cached epics to the user
3. If no cached epics found:
   - Query Jira:
     ```bash
     ngn-jira GET '/rest/api/3/search?jql=issuetype=Epic AND project=<PROJECT>&fields=summary,id&maxResults=50'
     ```
   - Save to hindsight:
     ```
     Tool: hindsight_retain
     tier: "epic-cache"
     content: "Epic Cache [2026-06-15]: PROJECT=PLATFORM: [PLATFORM-10: CI/CD Pipeline, PLATFORM-11: Infrastructure Migration, PLATFORM-12: Security Hardening]"
     ```

State of the Art

Old Approach Current Approach When Changed Impact
(v1.0) No session workflow — ad-hoc per session SKILL.md with structured session lifecycle This phase Every session follows the same init→work→close pattern. Consistent, documented, auditable.
(v1.0) No cross-session similarity awareness hindsight_recall check on every session start Phase 5 + This phase Agent can detect and offer to resume similar previous work. Saves time, reduces duplication.
(v1.0) Jira tickets created manually or not at all Agent creates Task tickets per session (prompted) This phase Clear traceability from session work to Jira tickets. Epics link work to larger initiatives.
(v1.0) No session documentation in Confluence Confluence pages tagged with ngn-agent This phase Searchable knowledge base of session outcomes. Team visibility.
(v1.0) No session summary persistence automatic hindsight_retain of structured summary Phase 5 + This phase Future hindsight_recall queries find relevant past sessions. Compounding knowledge base.

Deprecated/outdated:

  • Manual session setup: Every v1.0 session required the user to manually say "check my last session," "create a ticket," etc. The session skill automates this in a repeatable workflow.
  • Missing session documentation: Without D-12/D-13, past session work was invisible. The hindsight_retain at session end creates a searchable record.

Assumptions Log

# Claim Section Risk if Wrong
A1 The agent will reliably load the session skill when the "When to Use" conditions match Architecture Patterns — Skill Loading Medium risk. If the agent doesn't load the skill, the session workflow is skipped. Mitigation: Make "When to Use" very broad, include explicit trigger examples. User can always use /session or tell the agent to load the skill manually.
A2 The agent understands and follows skill_view("jira-query") cross-skill loading instructions from within a procedure Architecture Patterns — Cross-Skill Loading Low risk. skill_view is a standard Hermes tool. The agent uses it when instructed.
A3 hindsight_recall with a task description query returns session summaries that are identifiable as "previous sessions" Architecture Patterns — Similarity Search Low risk. Phase 5 config uses recall_types: observation and memory_mode: hybrid. Session summaries saved with tier: "session-summary" will be returned when semantically similar.
A4 The ngn-jira and ngn-confluence scripts are mounted and working inside Docker Standard Stack Low risk. Already verified in Phase 4 (v1.0). Phase 6 confirmed Docker script mounts exist.
A5 hindsight_retain accepts a tier field Architecture Patterns — Summary Save Low risk. The hindsight_retain tool from the Hermes plugin accepts structured content. The tier field is a convention for filtering during recall. Actual parameter names depend on the tool schema.
A6 The ngn-agent Confluence tag doesn't yet exist and needs to be created E2: Confluence Integration Low risk. If there are already pages with this tag, even better — search will find them. If not, the first session-end update will create the first tagged page.
A7 The skill file path ~/.hermes/skills/ngn-agent/session/SKILL.md is the correct location for Hermes discovery Standard Stack Very low risk. Hermes scans ~/.hermes/skills/ recursively for SKILL.md files. All 4 existing ngn-agent skills use subdirectories under ~/.hermes/skills/ngn-agent/.

Open Questions

  1. How does Hermes resolve skill names with nested directories?

    • What we know: Skills are stored in ~/.hermes/skills/<category>/<name>/SKILL.md. Hermes scans recursively. The skill's name in frontmatter is what appears in skills_list().
    • What's unclear: Does Hermes use the directory name or the frontmatter name field as the primary identifier? If the skill is at ngn-agent/session/SKILL.md with name: ngn-agent-session, does the agent see it as ngn-agent/session (path) or ngn-agent-session (frontmatter)?
    • Recommendation: Check with hermes skills list after installing. Set a clean frontmatter name (ngn-agent-session). Use both the directory path and frontmatter name in the procedure's skill_view() call to be safe. If in doubt, match the pattern of the existing 4 skills (which use directory names matching frontmatter names).

  2. What happens when skill_view() is called from within another skill's procedure?

    • What we know: skill_view is a tool the agent calls. It loads skill content into context.
    • What's unclear: Does the newly loaded skill's content REPLACE the current skill's content, or append? If it replaces, the session skill's remaining steps would be lost.
    • Recommendation: Design the procedure so cross-skill loading happens early and is optional. The Jira and Confluence operations are simple enough to encode directly in the session skill (using ngn-jira and ngn-confluence scripts) without loading the full skills. skill_view for jira-query/confluence-search is a nice-to-have for extra context, not a requirement.

  3. Does the agent need to save the Jira ticket key in memory to reference it at session end?

    • What we know: The session-end steps need the ticket key to add comments.
    • What's unclear: How does the agent remember the ticket key across a long session? Hindsight auto-retain may capture it, but the agent needs it in active context.
    • Recommendation: In the Procedure, tell the agent to note the ticket key explicitly in a way that persists across turns. For example: "After creating the ticket, remember the key (e.g., PLATFORM-123). You'll need it in the session-end step to add a summary comment."

Environment Availability

Dependency Required By Available Version Fallback
Hermes skill system SKILL.md file ✓ v0.16.x —
hindsight_recall tool Step 1 (similar session check) ✓ (Phase 5) — —
hindsight_retain tool Step 7 (session summary save) ✓ (Phase 5) — —
ngn-jira script Steps 2, 5 (Jira operations) ✓ (Phase 4, mounted) — —
ngn-confluence script Steps 3, 6 (Confluence operations) ✓ (Phase 4, mounted) — —
skill_view tool Cross-skill loading ✓ (Hermes built-in) — —
Hermes skill directory SKILL.md placement ✓ — —
skill_manage tool (optional) Agent-created skill patches ✓ (Hermes built-in) — —

Missing dependencies with no fallback: None — all tools and scripts are confirmed available from completed phases (4, 5, 6) and Hermes built-in capabilities.

Missing dependencies with fallback: None.

Validation Architecture

Skipped — workflow.nyquist_validation is explicitly false in .planning/config.json.

Security Domain

Applicable ASVS Categories

ASVS Category Applies Standard Control
V2 Authentication no No new authentication — reuses existing Jira/Confluence credentials via ngn-* scripts
V3 Session Management no Skill has no session state management
V4 Access Control no Skill is read-only orchestration; all mutations require user confirmation (D-08, D-11)
V5 Input Validation no No user input processed at the skill layer — user decisions are conversational
V6 Cryptography no No new cryptographic operations
V8 Data Protection yes Session summary saved to hindsight memory (local embedded PostgreSQL from Phase 5)

Known Threat Patterns

Pattern STRIDE Standard Mitigation
Prompt injection causing unauthorized Jira updates Tampering D-08: User must confirm before any Jira update. The Procedure explicitly says "ask the user first."
Prompt injection causing unauthorized Confluence updates Tampering D-11: User must confirm before any Confluence update. Same pattern as Jira.
Unintended hindsight_retain of sensitive information Information Disclosure The session summary is auto-saved (D-12) but only includes high-level outcomes, not raw conversation. Hindsight in local_embedded mode stores data locally.

Key Security Properties

  • User confirmation gates: Every write operation (Jira create, Jira update, Confluence create, Confluence update) is gated behind explicit user approval in the skill procedure
  • Auto-save is high-level only: The hindsight_retain summary is structured and contains only task-level information, not raw conversation transcripts
  • Read-only operations always allowed: hindsight_recall (read) and Confluence search (read) do NOT require user confirmation — only writes do

Sources

Primary (HIGH confidence)

  • Hermes official skills documentation — ~/.hermes/hermes-agent/website/docs/user-guide/features/skills.md (852 lines) — Complete SKILL.md format reference, progressive disclosure, skill bundles, cross-skill patterns [VERIFIED: read in full]
  • 4 existing ngn-agent SKILL.md files — ~/.hermes/skills/ngn-agent/*/SKILL.md — aws-diagnostics, jira, confluence, bitbucket — all follow identical frontmatter + When to Use + Procedure + Pitfalls format [VERIFIED: read all 4]
  • Phase 5 SUMMARY — .planning/phases/05-hindsight-memory-provider/05-01-SUMMARY.md — Confirms hindsight tools active with memory_mode: hybrid (3 tools available) [VERIFIED: read]
  • Phase 6 SUMMARY — .planning/phases/06-default-repos-ssh-mount/06-01-SUMMARY.md — Confirms repo mounts and ngn-* scripts available in Docker [VERIFIED: read]
  • CONTEXT.md — D-01 through D-14 locked decisions for this phase [VERIFIED: read]
  • initial-plan.md — func session() workflow specification [VERIFIED: read]

Secondary (MEDIUM confidence)

  • Hermes research docs — .planning/research/hermes/SKILLS.md, EXTENSIBILITY.md, SUMMARY.md — Skills system overview, plugin hook system, feature landscape [CITED: read]
  • FEATURES.md — .planning/research/FEATURES.md — Feature dependencies, prioritization [CITED: read]

Tertiary (LOW confidence)

  • Skill name resolution behavior — How Hermes resolves directory path vs frontmatter name for skill_view — not tested [ASSUMED: A1]
  • skill_view behavior within active skill — Whether loading another skill replaces or appends context — not verified [ASSUMED: Open Question 2]
  • hindsight_retain parameter names — Exact tool schema for tier field — inferred from Hindsight documentation [ASSUMED: A5]

Metadata

Confidence breakdown:

  • Standard stack: HIGH — All tools and scripts confirmed available from completed phases (4, 5, 6) and Hermes built-in capabilities
  • Architecture: HIGH — Patterns derived from Hermes official docs and 4 existing ngn-agent skills. Cross-skill orchestration is standard Hermes usage.
  • Pitfalls: HIGH — Pitfalls based on known Hermes skill behavior, Hindsight tool characteristics, and session workflow constraints from D-01 through D-14
  • Security: HIGH — All write operations gated behind user confirmation per locked decisions; read operations unrestricted

Research date: 2026-06-15 Valid until: 2026-07-15 (30 days — Hermes SKILL.md format is stable, Phase 5/6 dependencies are locked)

Reference in New Issue View Git Blame Copy Permalink