bapung/ngn-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0c890a65d595d18a8c80e009a09e602b475b367e
ngn-agent/.planning/PROJECT.md

5.7 KiB
Raw Blame History

ngn-agent

What This Is

ngn-agent is a platform engineering agent powered by Nous Research's Hermes Agent. It manages multi-project infrastructure work through isolated sessions, connects via Telegram gateway, runs commands in Docker containers with limited AWS IAM roles, and persists knowledge across sessions via Hermes' memory system. Designed for platform engineers who manage real infrastructure and need guardrails against accidental mutations.

Core Value

The agent must NEVER mutate real infrastructure beyond what the limited IAM role permits, while being maximally useful for diagnostics, research, and automation.

Requirements

Validated

  • ✓ Bedrock + OpenRouter provider chain — v1.0
  • ✓ Docker terminal backend with security hardening — v1.0
  • ✓ Limited dev_Restricted AWS SSO role via project-local .aws/ — v1.0
  • ✓ Dangerous command approval and hardline blocklist — v1.0
  • ✓ Hermes persistent memory with auto-save — v1.0
  • ✓ FTS5 session search — v1.0
  • ✓ Git worktree isolation — v1.0
  • ✓ Telegram gateway with DM pairing — v1.0
  • ✓ Skills system with 4 custom ngn-agent skills — v1.0
  • ✓ Jira, Confluence, Bitbucket API wrappers — v1.0
  • ✓ Cron/automation system active — v1.0
  • ✓ SOUL.md with ngn-agent identity — v1.0

Active

  • MEM-01: Hindsight memory provider enabled for cross-session recall
  • REPO-01: DEFAULT_REPOS auto-cloned into new sessions via shell_init_files
  • REPO-02: On-demand additional repo cloning during session
  • SKIL-04: Main ngn-agent session skill — session init, Jira ticket creation, doc loading, session-end updates
  • CRON-01: Daily session summary report delivered via Telegram
  • CRON-02: Stale session auto-archive (30d inactivity) with JSON export
  • CRON-03: Daily report integrates Jira ticket status via ngn-jira

Out of Scope

  • Direct ~/.aws mounting — use scoped ./.aws instead
  • Full kubectl exec / terraform apply access without explicit approval gates
  • Non-AWS cloud providers (GCP/Azure) — defer to future
  • Native mobile app — Telegram gateway is the mobile interface
  • Self-hosted model serving — use Bedrock/OpenRouter
  • Automated stale session archive (30d cleanup) — deferred from v1.0
  • Memory provider scaling (Honcho/Holographic) — deferred from v1.0

Out of Scope

  • Direct ~/.aws mounting — use scoped ./.aws instead
  • Full kubectl exec / terraform apply access without explicit approval gates
  • Non-AWS cloud providers (GCP/Azure) — defer to future
  • Native mobile app — Telegram gateway is the mobile interface
  • Self-hosted model serving — use Bedrock/OpenRouter

Context

  • Base tool: Nous Research Hermes Agent (Python/uv, MIT)
  • Runtime: macOS (Orbstack for Docker), CLI-only install (no Desktop)
  • LLM: AWS Bedrock (primary) via boto3 SSO auth → OpenRouter (fallback)
  • Terminal backend: Docker with hardened security (--cap-drop ALL, no-new-privileges)
  • Memory: Hermes persistent memory (MEMORY.md + USER.md) + FTS5 session search
  • Credentials: ./.aws/ with limited IAM role mounted read-only into Docker; ~/.hermes/.env for OpenRouter key
  • AWS auth: SSO role chaining with cached session (~7 day refresh), browser login on expiry
  • Project location: /Users/bapung/Razer/ngn-agent

Constraints

  • Security: Agent must run inside Docker with limited capabilities
  • Credential: Only scoped AWS role — never raw admin access
  • Auth: Bedrock uses boto3 chain (SSO); no API key for primary provider
  • Provider: OpenRouter key in .env for fallback only
  • Git: Worktree-based isolation; pushes only to feature branches
  • Gateway: Telegram as primary messaging channel

Current Milestone: v1.1 Session Lifecycle, Memory & Reporting

Goal: Productionize session workspace with default repos, upgrade to persistent cross-session memory (hindsight), and operationalize daily reporting with session lifecycle management.

Target features:

  • Default repos auto-cloned into every new Hermes session
  • On-demand repo cloning during sessions
  • Hindsight long-term memory provider
  • Daily cron report (session summaries via Telegram)
  • Stale session auto-archive (30d)
  • Jira integration in daily reporting

Key Decisions

Decision Rationale Outcome
Hermes Agent over NanoClaw Superior memory system (auto-learning, session search, 8 external providers) ✓ Good
Bedrock primary + OpenRouter fallback Zero additional API cost for primary (uses existing AWS SSO); OpenRouter as reliability layer — Pending
Docker backend Container isolation is the security boundary; dangerous command checks skipped — Pending
Project-local ./.aws Prevents privileged credentials from entering container — Pending
CLI-only install Desktop not needed; minimal surface area — Pending
Git worktree isolation Prevents branch contamination across sessions — Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

  1. Requirements invalidated? → Move to Out of Scope with reason
  2. Requirements validated? → Move to Validated with phase reference
  3. New requirements emerged? → Add to Active
  4. Decisions to log? → Add to Key Decisions
  5. "What This Is" still accurate? → Update if drifted

After each milestone (via /gsd-complete-milestone):

  1. Full review of all sections
  2. Core Value check — still the right priority?
  3. Audit Out of Scope — reasons still valid?
  4. Update Context with current state

Last updated: 2026-06-14 — v1.0 shipped, v1.1 in planning

Reference in New Issue View Git Blame Copy Permalink