115 lines
6.5 KiB
Markdown
115 lines
6.5 KiB
Markdown
# 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*
|