Add optional zero-config project scaffold and minimal init workflow

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.

Start by reviewing the existing CLI entry points for `agentik init` and `agentik run`, then compare the proposed locations in `examples/quickstart/`, a companion package, and the core package. Define the smallest placement and scope that can generate the listed scaffold, load context, enforce policy, persist sessions, and preserve existing APIs; completion is demonstrated by the acceptance criteria.

Written by the indexing model from the issue text.