---
phase: 01-framework-kernel-foundation
plan: 01
subsystem: kernel
tags: [go, cobra, koanf, plugins, cli, workspace]

requires: []
provides:
  - Manifest-driven code generation and app build
  - Required plugin interface and activation
  - Shared cobra command construction
  - Ordered hello plugin manifest
affects: [01-02, 01-03, 01-04]

tech-stack:
  added:
    - github.com/spf13/cobra v1.10.2
    - github.com/knadh/koanf/v2 v2.3.6
    - github.com/knadh/koanf/parsers/yaml v1.1.1
  patterns:
    - Compiled plugins self-register in init(); Activate orders by Requires()
    - Shared bonfire.NewRoot used by tool and app
    - summer.yaml ordered plugin list drives generated imports

key-files:
  created:
    - party/registry.go
    - backpack/app.go
    - pact/capabilities.go
    - compass/config.go
    - bonfire/command.go
    - bonfire/root.go
    - internal/build/build.go
    - cmd/summer/main.go
    - examples/hello/summer.yaml
    - examples/hello/main.go
    - examples/hello/plugins.gen.go
    - go.work
  modified:
    - go.mod
    - go.sum
    - .gitignore

key-decisions:
  - "Plugin lives in party with Register/Boot(*backpack.App); backpack does not import party"
  - "bonfire.NewRoot takes []bonfire.Command, not a party registry"
  - "HasConfig.ConfigFS() named to match Plan 02"
  - "Example modules use local replace for unpublished git.golem15.com/golem15/summercms v0.0.0"
  - "Pin toolchain go1.27.0 in go.work and every example go.mod"

patterns-established:
  - "Pattern: blank-import plugins.gen.go plus explicit PluginIDs slice; never use init order for lifecycle"
  - "Pattern: summer build validates module paths, quotes imports, and execs go build with separate args"

requirements-completed: [KERN-01, KERN-02, KERN-03, KERN-04, CLI-01]

duration: 15min
completed: 2026-09-16
---

# Phase 1 Plan 1: Hello App Kernel Summary

**Compiled-plugin hello app boots via party.Activate and runs greeter:hello through a shared cobra/bonfire kernel, built by `summer build` from an ordered summer.yaml manifest**

## Performance

- **Duration:** 15 min
- **Started:** 2026-09-16T10:47:05Z
- **Completed:** 2026-09-16T11:02:48Z
- **Tasks:** 2
- **Files modified:** 30

## Accomplishments

- Framework kernel packages (`party`, `backpack`, `pact`, `compass`, `bonfire`) boot two compiled hello plugins with all Register calls before any Boot
- Permanent `examples/hello` app prints `app.name` from `config/app.yaml` via `greeter:hello`
- `cmd/summer build` generates stable `main.go`/`plugins.gen.go` from `summer.yaml` and produces `bin/hello` without importing example plugins

## Task Commits

Each task was committed atomically:

1. **Task 1: Make the hello app boot and dispatch a plugin command** - `96a8d38` (feat)
2. **Task 2: Generate and build the hello app from its ordered manifest** - `2078f91` (feat)

**Plan metadata:** pending (docs: complete plan)

## Files Created/Modified

- `party/registry.go` - Plugin interface, init registry, topo-sorted Activate
- `backpack/app.go` - App container holding compass config; no party import
- `pact/capabilities.go` - HasCommands, HasConfig; reserved KERN-03 names documented
- `compass/config.go` - Load config/<section>.yaml and String dot-path lookup
- `bonfire/command.go` / `bonfire/root.go` - Command values, Input/Output, shared cobra root
- `internal/build/build.go` - Manifest parse, validated codegen, `go build` via CommandContext
- `cmd/summer/main.go` - Framework tool entry using the same NewRoot
- `examples/hello/` - Workspace app, two plugin modules, summer.yaml, generated main
- `go.mod` / `go.work` - cobra, koanf, toolchain go1.27.0, four workspace modules

## Decisions Made

- Keep `Plugin` in `party` taking `*backpack.App` so `backpack` never imports `party`
- `bonfire.NewRoot(name, []Command, io.Writer)` is the single command kernel for tool and app
- Name `HasConfig.ConfigFS()` now so Plan 02 can load embedded plugin defaults without a rename
- Add `replace` lines in example `go.mod` files; D-04 allows go.work or local replace, and `v0.0.0` is not fetchable from the private module host
- Re-pin `toolchain go1.27.0` after `go mod tidy`, which drops a matching toolchain line

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Local replace for unpublished framework module**
- **Found during:** Task 1 (module tidy)
- **Issue:** `go mod tidy` in example modules tried to fetch `git.golem15.com/golem15/summercms@v0.0.0` over HTTPS and failed (private host, no tag)
- **Fix:** Added `replace git.golem15.com/golem15/summercms => <relative>` in hello/plugin go.mod files, which D-04 already allows
- **Files modified:** `examples/hello/go.mod`, `examples/hello/plugins/base/go.mod`, `examples/hello/plugins/greeter/go.mod`
- **Verification:** `go vet`/`go test` in root and hello
- **Committed in:** `96a8d38` (Task 1)

**2. [Rule 2 - Missing Critical] Restore toolchain directive after tidy**
- **Found during:** Task 1
- **Issue:** `go mod tidy` removed `toolchain go1.27.0` from go.mod files because the local toolchain already matched
- **Fix:** Re-added the directive to root and all example modules plus `go.work` (D-05)
- **Files modified:** `go.mod`, `examples/hello/go.mod`, plugin go.mod files, `go.work`
- **Verification:** files contain `toolchain go1.27.0`
- **Committed in:** `96a8d38` (Task 1)

---

**Total deviations:** 2 auto-fixed (1 blocking, 1 missing critical)
**Impact on plan:** Required for a buildable workspace of unpublished modules and the D-05 toolchain pin. No scope creep.

## Issues Encountered

- Spawn HEAD was `master` on this isolated Grok clone (`.git` is a directory, not a linked worktree). Created `worktree-agent-01a0a9d2` from `552cadb` without rewriting `refs/heads/master`. Commits live on the agent branch.

## Authentication Gates

None.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

Ready for `01-02-PLAN.md` (layered compass config, optional plugin composition, services, typed events). Hello already boots and `summer build` is the shared generate-and-compile function later plans extend.

## Self-Check: PASSED

- Created kernel, hello, and build files exist on disk
- Commits `96a8d38` and `2078f91` exist
- Root and hello `go vet ./...` and `go test ./...` passed
- Two `summer build` runs left `main.go`/`plugins.gen.go` hashes unchanged; `./bin/hello greeter:hello` printed `hello-app`
- `go list -deps ./cmd/summer` has no hello plugin packages
- STATE.md and ROADMAP.md were not updated in this worktree

---
*Phase: 01-framework-kernel-foundation*
*Completed: 2026-09-16*