docs(09): capture phase context
This commit is contained in:
130
.planning/phases/09-tooling-portable-setup/09-CONTEXT.md
Normal file
130
.planning/phases/09-tooling-portable-setup/09-CONTEXT.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Phase 9: Tooling & Portable Setup - Context
|
||||
|
||||
**Gathered:** 2026-06-14
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
Create a custom Docker image with essential platform engineering tools and a portable setup script that can provision a fresh macOS machine with all ngn-agent configuration in a single invocation.
|
||||
|
||||
**In scope:** Custom Dockerfile in project repo, image build tooling, parameterized setup script covering all config, file creation, volume mounts, skills, and cron jobs
|
||||
|
||||
**Out of scope:** Installing Hermes Agent itself (assumes Hermes v0.16+ is installed), cloud-native deployment (macOS-only setup), multi-architecture image builds
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Custom Docker Image
|
||||
- **D-01:** Dockerfile lives in this repo at `ngn-agent/docker/Dockerfile` — extends `nikolaik/python-nodejs:python3.11-nodejs20`
|
||||
- **D-02:** Pin specific tool versions — Dockerfile should specify exact versions for reproducibility
|
||||
- **D-03:** Tools to include:
|
||||
- **aws-cli**: v2 (latest stable)
|
||||
- **terraform**: latest stable
|
||||
- **helm**: latest stable
|
||||
- **kubectl**: latest stable matching cluster version
|
||||
- **datadog CLI** (`pup`): latest stable
|
||||
- **D-04:** Build script at `ngn-agent/docker/build.sh` — single command to build the image
|
||||
- **D-05:** Image tag: `ngn-agent:latest` (local only, no registry push)
|
||||
|
||||
### Portable Setup Script
|
||||
- **D-06:** Single script at `ngn-agent/setup-ngn-agent.sh` — recreates all configuration on a fresh machine
|
||||
- **D-07:** Assumes Hermes v0.16+ is already installed and `hermes` CLI is on PATH
|
||||
- **D-08:** Interactive prompts for all secrets:
|
||||
- `JIRA_API_TOKEN` (required for Atlassian integrations)
|
||||
- `JIRA_EMAIL` (required for Atlassian integrations)
|
||||
- `TELEGRAM_BOT_TOKEN` (required for gateway)
|
||||
- `OPENROUTER_API_KEY` (if not already set)
|
||||
- **D-09:** Configurable parameters (supplied via args or prompts):
|
||||
- SSH key paths (default: `~/.ssh/id_ed25519razer`, `~/.ssh/id_rsa`)
|
||||
- SSH config path (default: `~/.ssh/config`)
|
||||
- SSH known_hosts path (default: `~/.ssh/known_hosts`)
|
||||
- Repo paths (default: `~/Razer/rai-ops`, `~/Razer/rai-deployment`, `~/Razer/rai-devtools`)
|
||||
- Timezone (default: `Asia/Singapore`)
|
||||
- **D-10:** What the setup script creates/updates:
|
||||
- `~/.hermes/config.yaml` — docker_volumes (SSH + repo mounts), shell_init_files, docker_forward_env, cron config
|
||||
- `~/.hermes/.env` — secrets and DEFAULT_REPOS
|
||||
- `~/.hermes/hindsight/config.json` — Hindsight config
|
||||
- `~/.hermes/scripts/session-init.sh` — mount verification script
|
||||
- `~/.hermes/scripts/archive-stale-sessions.sh` — archive script
|
||||
- `~/.hermes/skills/ngn-agent/` — all 5 skill directories
|
||||
- `~/.hermes/archive/sessions/` — archive directory
|
||||
- Register 3 cron jobs (ngn-daily-report, ngn-weekly-stale-summary, ngn-weekly-archive)
|
||||
- Update Docker image reference in config.yaml
|
||||
|
||||
### the agent's Discretion
|
||||
- **Dockerfile tool version selection**: Choose stable versions current at time of implementation
|
||||
- **Setup script structure**: Interactive prompt flow, output formatting, error handling approach
|
||||
- **Config file templates**: How to generate config.yaml sections, .env format, etc.
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Project Repo
|
||||
- `.planning/REQUIREMENTS.md` §TOOL-01, SETUP-01 — Requirement definitions
|
||||
- `.planning/ROADMAP.md` §Phase 9 — Phase goal and success criteria
|
||||
|
||||
### Current Configuration (what the setup script must recreate)
|
||||
- `~/.hermes/config.yaml` — Full config with docker_volumes, shell_init_files, docker_forward_env, cron, memory.provider, telegram
|
||||
- `~/.hermes/.env` — All env vars (JIRA_API_TOKEN, JIRA_EMAIL, TELEGRAM_BOT_TOKEN, OPENROUTER_API_KEY, DEFAULT_REPOS, HINDSIGHT_LLM_API_KEY)
|
||||
- `~/.hermes/hindsight/config.json` — Hindsight local_embedded config with all settings
|
||||
- `~/.hermes/scripts/session-init.sh` — Mount verification script
|
||||
- `~/.hermes/scripts/archive-stale-sessions.sh` — Session archive script
|
||||
- `~/.hermes/skills/ngn-agent/` — 5 skill files (aws-diagnostics, jira, confluence, bitbucket, session)
|
||||
- `.planning/phases/08-cron-reporting/08-01-SUMMARY.md` — Cron job registrations
|
||||
- `.planning/phases/08-cron-reporting/08-02-SUMMARY.md` — Weekly cron job details
|
||||
|
||||
### Base Image
|
||||
- `nikolaik/python-nodejs:python3.11-nodejs20` — Current Hermes Docker image
|
||||
|
||||
### Existing Skills (templates for setup script)
|
||||
- `~/.hermes/skills/ngn-agent/aws-diagnostics/SKILL.md`
|
||||
- `~/.hermes/skills/ngn-agent/jira/SKILL.md`
|
||||
- `~/.hermes/skills/ngn-agent/confluence/SKILL.md`
|
||||
- `~/.hermes/skills/ngn-agent/bitbucket/SKILL.md`
|
||||
- `~/.hermes/skills/ngn-agent/session/SKILL.md`
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- **Hermes config.yaml** — Current state is the source of truth for what setup script must recreate
|
||||
- **Skill files** — 5 existing SKILL.md files that setup script must copy into place
|
||||
- **Script files** — session-init.sh and archive-stale-sessions.sh that setup script must copy
|
||||
- **Hindsight config.json** — Current config that setup script must create
|
||||
|
||||
### Integration Points
|
||||
- `ngn-agent/docker/Dockerfile` — New file (create)
|
||||
- `ngn-agent/docker/build.sh` — New file (create)
|
||||
- `ngn-agent/setup-ngn-agent.sh` — New file (create)
|
||||
- `~/.hermes/config.yaml` — Modified by setup script
|
||||
- `~/.hermes/.env` — Created by setup script with user-provided secrets
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- The setup script should use `hermes config set` where possible instead of raw YAML editing
|
||||
- Secrets should be prompted interactively with masked input where the terminal supports it
|
||||
- The setup script should validate prerequisites (Hermes installed, Docker running, SSH keys exist) before making changes
|
||||
- The Dockerfile should install tools via apt-get and pip where possible, with version pinning via checksums or apt version strings
|
||||
- After setup, script should offer to restart the Hermes gateway
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- Multi-architecture image builds (arm64 + amd64) — defer until needed
|
||||
- Cloud-native deployment (Docker Compose, Fly.io, etc.) — out of scope
|
||||
- CI/CD for image builds — out of scope
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 9-Tooling & Portable Setup*
|
||||
*Context gathered: 2026-06-14*
|
||||
@@ -0,0 +1,45 @@
|
||||
# Phase 9: Tooling & Portable Setup - Discussion Log
|
||||
|
||||
> **Audit trail only.**
|
||||
|
||||
**Date:** 2026-06-14
|
||||
**Phase:** 9-Tooling & Portable Setup
|
||||
**Areas discussed:** Custom Docker image, Setup script approach
|
||||
|
||||
---
|
||||
|
||||
## Custom Docker Image
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| In this repo | Dockerfile in ngn-agent repo, pin tool versions | ✓ |
|
||||
| Dedicated repo | Separate repo for image build | |
|
||||
|
||||
**User's choice:** In this repo, pin tool versions
|
||||
**Notes:** Dockerfile at `ngn-agent/docker/Dockerfile`, build script at `ngn-agent/docker/build.sh`.
|
||||
|
||||
---
|
||||
|
||||
## Setup Script Approach
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Full setup + config | All config, secrets prompted, directory creation, volume mounts, skills, cron | ✓ |
|
||||
| Config only | Just copy config files | |
|
||||
|
||||
**User's choice:** Full setup. Secrets specified during setup with interactive prompts.
|
||||
**Notes:** Script creates everything. Assumes Hermes installed. Interactive prompts for secrets.
|
||||
|
||||
---
|
||||
|
||||
## the agent's Discretion
|
||||
|
||||
- Dockerfile tool version selection
|
||||
- Setup script interactive flow design
|
||||
- Config file template generation
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Multi-architecture builds
|
||||
- Cloud-native deployment
|
||||
- CI/CD for images
|
||||
Reference in New Issue
Block a user