From e4d7f341128407a28f784f963d3d6fabff71e2a4 Mon Sep 17 00:00:00 2001 From: Bagas Purwa Sentika Date: Mon, 15 Jun 2026 20:13:52 +0800 Subject: [PATCH] docs(07): capture phase context --- .../07-main-session-skill/07-CONTEXT.md | 114 ++++++++++++++++++ .../07-DISCUSSION-LOG.md | 54 +++++++++ 2 files changed, 168 insertions(+) create mode 100644 .planning/phases/07-main-session-skill/07-CONTEXT.md create mode 100644 .planning/phases/07-main-session-skill/07-DISCUSSION-LOG.md diff --git a/.planning/phases/07-main-session-skill/07-CONTEXT.md b/.planning/phases/07-main-session-skill/07-CONTEXT.md new file mode 100644 index 0000000..ee1e618 --- /dev/null +++ b/.planning/phases/07-main-session-skill/07-CONTEXT.md @@ -0,0 +1,114 @@ +# 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 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 + + + +## 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 + + + +## 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* diff --git a/.planning/phases/07-main-session-skill/07-DISCUSSION-LOG.md b/.planning/phases/07-main-session-skill/07-DISCUSSION-LOG.md new file mode 100644 index 0000000..bda0891 --- /dev/null +++ b/.planning/phases/07-main-session-skill/07-DISCUSSION-LOG.md @@ -0,0 +1,54 @@ +# Phase 7: Main Session Skill - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-06-14 +**Phase:** 7-Main Session Skill +**Areas discussed:** Session start behavior, Jira integration, Confluence docs, Session-end behavior + +--- + +## Session Start Behavior + +**User's choice:** Auto-check hindsight for similar sessions (<2 weeks). Jira ticket creation should prompt. Doc loading should prompt — docs need to search. + +**Notes:** Three-tier behavior — similar sessions (auto), Jira (prompt), docs (prompt + search by tag). + +--- + +## Jira Integration + +**User's choice:** Always create Task type. Default board configurable later. Query available epics and cache in long-term memory — fetch occasionally or when asked. + +**Notes:** Epic cache lives in hindsight memory. Don't fetch epics every session — use cached version, refresh on demand. + +--- + +## Confluence Doc Search + +**User's choice:** Create a tag for ngn-agent. Search Confluence by that tag and do matching. + +**Notes:** Tag name TBD (default: `ngn-agent`). Present matching pages, user selects which to load. + +--- + +## Session-End Behavior + +**User's choice:** Always ask before Jira/Confluence updates. Always save session to hindsight (no prompt). + +**Notes:** Session save is automatic. Jira comment and Confluence update are prompted. + +--- + +## the agent's Discretion + +- Exact tag name for Confluence searches +- Epic cache refresh interval +- Similar session display format + +## Deferred Ideas + +- Daily reporting cron (Phase 8) +- Stale session archive (Phase 8) +- Auto-create Jira tickets (user wants manual control)