agentik

Summary This PR introduces an opt-in project scaffold and repo-aware context loader for the CLI. The goal is to reduce onboarding friction by enabling a deterministic, repo-aware agent workflow with only a selected model and API key, while preserving Agentik’s runtime-first philosophy and existing behavior. No breaking changes. Existing workflows remain unchanged when the scaffold is not present. What This Adds 1. Command A new CLI subcommand that generates a minimal scaffold in the current directory: AGENTIK.md PROJECT_STATE.md .agentik/ settings.json rules/ 00-safety.md 10-style.md sessions/ This scaffold is fully optional and editable. 2. Repo Context Loading (Opt-In) When exists in the working directory, the CLI automatically assembles a deterministic context pack in this order: 1. 2. 3. sorted lexicographically This context is injected before the first user turn. If the scaffold does not exist, behavior is unchanged. 3. Minimal Policy Enforcement Layer Using existing lifecycle hooks in the CLI: Deny access to common secret paths such as , , and Require approval for , , and tools, configurable via settings Block approval-required tools in print mode Persist tool events to the session store when enabled All enforcement is additive and driven by . 4. Default File-Based Session Persistence When scaffold exists and persistence is enabled: Sessions are stored locally using existing session primitives. No persistence behavior changes when scaffold is absent. Bun Execution Policy Bun is used for local execution using and . No lockfile changes are committed. All lockfiles including , , , , and are excluded from modification. Clean state verified before PR via . Why Currently, users must manually wire: Context files Settings schema Policy enforcement Session persistence CLI glue This PR provides a minimal reference convention that demonstrates how these pieces fit together without expanding the runtime surface area. Benefits: Lower onboarding friction Clear best-practice example Fully opt-in No change to existing APIs No change to runtime behavior Non-Goals Converting Agentik into a monolithic CLI Changing runtime defaults Enforcing conventions on advanced users Introducing breaking changes How to Test Run: Context should reflect scaffold files Writes to should be blocked Without scaffold present, CLI behavior remains unchanged Happy to iterate on placement, naming, or scope if preferred elsewhere such as an examples directory instead of the CLI package.

Summary Agentik provides a powerful runtime, reference CLI, and built-in tools. However, first-time users must manually wire context loading, tool policy, session persistence, and lifecycle hooks before they can experience a deterministic, repo-aware agent workflow. This proposal adds an optional, additive scaffold layer that enables a working agent with only: • a selected model • a valid API key • a single command The goal is to reduce onboarding friction while preserving Agentik’s runtime-first philosophy. ⸻ Problem Today, a new user who wants a repo-aware coding agent must: 1. Create context files manually 2. Design a settings schema 3. Implement a context loader 4. Implement tool authorization logic 5. Wire lifecycle hooks 6. Configure session persistence While the runtime exposes all required primitives, there is no convention layer or minimal scaffold that demonstrates how these components fit together in practice. This results in: • onboarding friction • duplicated boilerplate across users • inconsistent patterns • unclear intended usage for repo-aware workflows ⸻ Proposal Add an optional scaffold and minimal loader layer that: • Does not change existing runtime APIs • Does not impose conventions on advanced users • Lives either in examples/, a companion package, or a small additive CLI feature • Demonstrates a complete deterministic workflow built on top of existing primitives ⸻ Proposed Scope 1. Default Project Structure Provide a minimal scaffold generated via: agentik init It creates: AGENT.md PROJECT_STATE.md .agent/ settings.json rules/ 00-safety.md 10-style.md sessions/ Purpose: • Demonstrates structured context layering • Provides editable templates • Encourages consistent usage patterns ⸻ 2. Minimal settings.json Schema Ship a documented baseline schema: { "model": { "provider": "anthropic", "name": "claude-3-7-sonnet", "temperature": 0.2 }, "tools": { "bash": { "enabled": true, "requireApproval": true }, "writeFile": { "enabled": true, "requireApproval": true }, "readFile": { "enabled": true } }, "qualityGates": { "requireTestsPassing": false } } This becomes: • the enforcement layer for lifecycle hooks • a clear extensible policy surface • a reference example of best practices ⸻ 3. Default Context Loader Add a minimal loader used by the CLI or example. Context assembly order: 1. AGENT.md 2. PROJECT_STATE.md 3. .agent/rules/*.md sorted 4. Optional active plan file This produces a deterministic context pack without custom wiring. ⸻ 4. Reference Policy Enforcement Use lifecycle hooks to implement a minimal policy layer: • Deny access to .env and secrets • Require approval for write, edit, bash • Log tool calls to .agent/sessions/ • Optional test or lint gate before completion This demonstrates intended hook usage. ⸻ 5. Default File-Based Session Store Out of the box: .agent/sessions/.jsonl Automatically created on first run. No custom store required for basic usage. ⸻ 6. Single-Command Experience After install and API key: agentik init agentik run "summarize this repository" This should: • Load scaffold • Enforce tool policy • Persist session • Run with built-in tools • Stream output No additional wiring required. ⸻ Implementation Placement Options Open question: Where should this live? 1. examples/quickstart/ 2. Companion package such as @agentik/create 3. Small addition to @jaredpalmer/coding-agent 4. Core package Preferred placement is examples or a companion package to avoid expanding core surface area. ⸻ Non-Goals • Turning Agentik into a monolithic CLI • Replacing flexibility • Enforcing mandatory conventions • Modifying runtime behavior • Introducing breaking changes This is entirely opt-in. ⸻ Acceptance Criteria • Installing the package and setting an API key is sufficient to run an agent in a repo • Scaffold is generated via a single command • Existing APIs remain unchanged • Advanced users can ignore scaffold entirely • Documentation clearly distinguishes runtime primitives from scaffold layer ⸻ Why This Improves the Project • Reduces onboarding friction • Establishes best practices • Makes demos easier • Encourages adoption • Reduces repeated boilerplate ⸻ Offer If aligned with project goals, I am willing to submit a PR implementing: • The scaffold generator • The minimal loader • The reference policy enforcement • Documentation updates Please advise preferred placement and scope boundaries.