Architecture

The hjemmesidekongen/ai methodology is implemented as five plugins with one foundation. Each plugin has a clear responsibility boundary, communicates through data files, and never imports another plugin's skills directly. This architecture reflects the methodology's core constraint: agents work, but within strict boundaries.

Plugin Hierarchy

kronen             ← foundation, always installed
├── smedjen          ← development execution, depends on kronen
├── herold            ← task management, depends on kronen
├── våbenskjold       ← brand strategy, depends on kronen
└── segl              ← visual identity + design tokens, depends on kronen

Rules:

• Every plugin depends on kronen. Nothing else.
• Plugins never depend on each other directly — they communicate through shared data files.
• Cross-plugin coordination happens through shared data files (e.g., smedjen's agent-dispatcher reads herold's task files but never calls herold commands directly).
• Brand-to-design pipeline: våbenskjold writes .ai/brand/ → segl reads it and writes .ai/design/ → smedjen's design-to-code patterns consumes tokens. Each step is independent.

Responsibility Boundaries

Data Flow

                    ┌───────────────────┐
                    │    kronen    │
                    │                   │
                    │  .ai/context/     │  Session state, snapshots
                    │  .ai/plans/      │  Wave plans, verification
                    │  .ai/instincts/  │  Learning pipeline
                    │  .ai/roadmap.yml │  Project roadmap
                    └─────┬─────┬──────┘
                          │     │
              ┌───────────┘     └───────────┐
              ▼                             ▼
    ┌─────────────────┐          ┌─────────────────┐
    │    herold      │          │   smedjen     │
    │                  │          │                  │
    │  .ai/tasks/     │ ──read── │  .ai/project-    │
    │    <KEY>.yml    │          │    map.yml       │
    │    active.yml   │◄─ read ──│  .ai/smedjen/ │
    │    handoff.yml  │          │    pipeline.yml  │
    └─────────────────┘          └──────────────────┘

herold writes task files. smedjen reads them directly (agent-dispatcher loads task context from .ai/tasks/). våbenskjold writes brand files to .ai/brand/. segl reads brand files and writes design files to .ai/design/. No plugin writes to another plugin's directories.

Hooks Architecture

Only kronen defines hooks. Other plugins operate through skill and command invocation.

Hooks are the safety net that prevents: pushing to main, skipping verification, modifying out-of-scope files, and premature completion claims.

Agent Model

Agents follow strict separation of concerns:

Implementing agents (sonnet tier) - write code, build features, fix bugs. They never mark their own work complete.

Review agents (opus tier) - evaluate work, check quality, run verification. They never modify code. The code-reviewer is the only agent authorized to approve task completion.

This separation prevents self-grading. The agent that writes the code never decides if the code is good enough.

File Ownership

When multiple agents work in parallel, each gets exclusive write access to specific files:

agent-1  →  owns: src/components/Foo.tsx
agent-2  →  owns: src/api/foo.ts
agent-3  →  owns: tests/foo.test.ts

If two agents need the same file, the dispatcher serializes those tasks. Interface contracts are defined at boundaries before implementation starts.

MCP Integration Pattern

All MCP-dependent features follow a two-layer pattern:

1. kronen basics skill - raw MCP interaction (e.g., jira-basics handles API calls, auth, pagination)
2. herold orchestration skill - adds task awareness (e.g., jira-ingestion normalizes tickets, runs contradiction detection)

This means you can use Jira from kronen directly for ad-hoc queries, or through herold for structured ticket workflows.

Every MCP integration degrades gracefully:

• If the MCP server isn't configured → clear error message
• If the server is unavailable → dry-run mode or empty results
• Never fabricated data, never silent failures

State Management

All state persists as YAML files in .ai/:

No databases. No external services for state. Everything is local, versionable, and inspectable.

Session Continuity

Claude Code loses all context between sessions and during compaction. The plugins handle this:

1. PreCompact hook → saves snapshot.yml with current state
2. SessionStart hook → restores state from snapshot.yml
3. session-handoff → manual save/resume for cross-session work
4. CLAUDE.md pointer → "after /compact, read .ai/context/snapshot.yml"
5. State files → plans, tasks, and roadmap persist on disk regardless of session state

Verification Model

Three layers of verification prevent incomplete work from shipping:

1. verification-gate (kronen) - 5-step proof protocol: identify → run → read → verify → claim
2. plan-verifier (kronen) - two-stage wave verification: mechanical spec compliance, then quality review
3. completion-gate (smedjen) - 10-point quality criteria run by the code-reviewer agent

All three are mandatory. None can be bypassed by the implementing agent.

See also

• kronen - the foundation plugin with hooks, verification, and state management
• smedjen - the development execution pipeline and agent model
• herold - task lifecycle and MCP integrations
• våbenskjold - brand strategy toolkit
• segl - visual identity and design tokens