docs(07): capture phase context
This commit is contained in:
114
.planning/phases/07-main-session-skill/07-CONTEXT.md
Normal file
114
.planning/phases/07-main-session-skill/07-CONTEXT.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# 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*
|
||||
54
.planning/phases/07-main-session-skill/07-DISCUSSION-LOG.md
Normal file
54
.planning/phases/07-main-session-skill/07-DISCUSSION-LOG.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user