Skip to content

feat: agentlayer init as unified onboarding entrypoint (ARB-28) #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
iMark21 merged 1 commit into from
Apr 23, 2026
Merged

feat: agentlayer init as unified onboarding entrypoint (ARB-28) #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,60 @@ jobs:
test "$status" -ne 0
test ! -d "$repo/.ai"

- name: init auto-routes to install on fresh repo
shell: bash
run: |
set -euo pipefail
repo="$(mktemp -d)"
git -C "$repo" init

bin/agentlayer init "$repo" \
--runtimes generic \
--project-type generic \
--yes \
--non-interactive > "$repo/init.log"

grep -q "Action: install" "$repo/init.log"
test -f "$repo/.ai/README.md"
test -f "$repo/AGENTLAYER.md"

- name: init auto-routes to standardize when AI files exist
shell: bash
run: |
set -euo pipefail
repo="$(mktemp -d)"
touch "$repo/CLAUDE.md"
git -C "$repo" init

bin/agentlayer init "$repo" \
--runtimes claude,generic \
--project-type generic \
--yes \
--non-interactive > "$repo/init.log"

grep -q "Action: standardize" "$repo/init.log"
grep -q "Existing AI files: yes" "$repo/init.log"
test -f "$repo/.ai/README.md"
test -d "$repo/.ai/archive"

- name: init with no path defaults to cwd
shell: bash
run: |
set -euo pipefail
repo="$(mktemp -d)"
git -C "$repo" init
cli="$(pwd)/bin/agentlayer"

cd "$repo"
"$cli" init \
--runtimes generic \
--project-type generic \
--yes \
--non-interactive > init.log

grep -q "Target repo: $repo" init.log
test -f .ai/README.md

- name: Standardize smoke test
shell: bash
run: |
Expand Down
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@ All notable changes to agentlayer are documented here.

## [Unreleased]

### Added
- `agentlayer init` — recommended single-entrypoint command. Detects repository state (fresh vs. already has AI files), asks once which runtime(s) to use, prints a preflight summary (target repo, project type, existing AI files, chosen action, runtimes), confirms, and routes to `install` or `standardize`. Path argument is optional; defaults to the current directory. `audit`, `install`, and `standardize` remain available for advanced/scripted use.
- README recut around the first-use path (`agentlayer init`). Internal structural detail moved to MANUAL.md.
- README "Alternative — let your AI install it" section now states the prerequisites explicitly: the assistant must have local read/write access to the repository; cloud-only chat tools do not work.

### Changed (UX, breaking in edge cases)
- `agentlayer install` now refuses to run on a repository that already has any AI-related file (`.ai/`, `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/agentlayer.mdc`, or `AGENTLAYER.md`). The CLI exits non-zero and points at `agentlayer standardize`. The previous behavior (warn + optional prompt to continue) could leave a repo in a mixed state.
- `agentlayer install --non-interactive` without `--runtimes` now exits non-zero with an explicit error. Previously it silently fell back to a detected default (e.g. `codex,claude,generic`) and generated adapters the user had not asked for.
Expand Down
33 changes: 30 additions & 3 deletions MANUAL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,34 @@ This is the safest default when you need the setup to survive tool churn.

## Commands

### 1. Audit
`init` is the recommended entrypoint; `install`, `standardize`, and `audit` remain available for advanced or scripted usage.

### 1. Init (recommended)

Single entrypoint that detects the repository state and routes to the right underlying command.

```bash
# Inside a repo
cd /path/to/repo
agentlayer init

# Or with an explicit path
agentlayer init /path/to/repo --runtimes claude,generic
```

What it does:

- resolves the target path (`.` if omitted) and detects the project type
- scans for pre-existing AI files (`.ai/`, `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/agentlayer.mdc`, `AGENTLAYER.md`)
- asks once which runtime(s) to generate, if not passed via `--runtimes`
- prints a preflight summary (target repo, project name, project type, detected AI files, chosen action, runtimes)
- asks for confirmation before running — skipped under `--yes`
- calls `install` if the repo is fresh, or `standardize` if AI files are already present
- under `--non-interactive`, requires `--runtimes` explicitly; otherwise it exits with an error

`init` never modifies the install/standardize logic — it only decides which one to invoke.

### 2. Audit

Read-only mode.

Expand All @@ -229,7 +256,7 @@ bin/agentlayer audit /path/to/repo \
--report-path /tmp/agentlayer-audit.md
```

### 2. Install
### 3. Install

Use it when the repo does not yet have a canonical AI layer.

Expand All @@ -251,7 +278,7 @@ What it does:
- optionally applies local git user name and email
- prints the recommended first-pass context-bootstrap step for the selected runtimes

### 3. Standardize
### 4. Standardize

Use it when the repo already has AI-related files and you want to normalize it.

Expand Down
213 changes: 41 additions & 172 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,216 +4,85 @@

Your AI assistant writes better code when it actually knows your project.

agentlayer adds a structured context layer to any existing repository so that Codex, Claude Code, Copilot, Cursor — or any AI — stops guessing and starts following your real architecture, conventions, and decisions from the first prompt.
agentlayer adds a structured `.ai/` layer to any existing repository so that Codex, Claude Code, Copilot, Cursor — or any AI — stops guessing and starts following your real architecture, conventions, and decisions from the first prompt.

No dependencies. Any AI runtime. Any tech stack.

## Does this sound familiar?
## Install

- You open Codex or Claude on an existing project and the first ten minutes are spent explaining the architecture, again
- Your `AGENTS.md` or `CLAUDE.md` has grown to 200+ lines and the AI still ignores half of it
- You ask the AI to add a feature and it invents a folder structure that does not match your project
- A new teammate joins and has to figure out the codebase from scratch because there is no structured context
- A legacy project has no AI setup at all and you do not know where to start
One command. It detects the repo state, asks which AI you use, and sets everything up.

agentlayer solves all of these. It gives your repository a canonical `.ai/` layer that any AI reads before acting — so it understands the product, follows your conventions, and remembers what was already built.

## What you get: a team of agents

When you install agentlayer, your repo gets a team of specialized agents that follow a structured workflow:
```bash
# 1. Get the CLI (clone somewhere persistent — /tmp gets cleaned and breaks the symlink)
git clone https://github.com/iMark21/agentlayer.git ~/.agentlayer
cd ~/.agentlayer && bash install.sh

# 2. Inside your repo
cd /path/to/your-repo
agentlayer init
```
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ agent-explore │──>│ agent-plan │──>│ agent-code │──>│ agent-verify │
│ │ │ │ │ │ │ │
│ Maps the area │ │ File-level plan │ │ Step-by-step │ │ Tests, criteria, │
│ before you touch │ │ with tests and │ │ implementation. │ │ residual risk. │
│ anything │ │ trade-offs │ │ Stops if blocked │ │ │
└──────────────────┘ └──────────────────┘ └──────────────────┘ └──────────────────┘
```

Plus specialized agents for **bug fixes** (`agent-fix`), **refactors** (`agent-tech`), and **investigations** (`agent-spike`).

Plus reusable skills: **context refresh**, **feature scaffold**, **migration audit**.

All generated automatically. Agents are Markdown playbooks — they work with any AI, not just one vendor.

## The structure is always the same. The content is yours.

Without agentlayer, asking an AI to "set up an AI layer" produces something different every time — whatever the model decides that session.

With agentlayer, every installation produces the same skeleton:

- 8 agents with defined responsibilities
- 4 reusable skills
- 5 context files for architecture, dependencies, features, repository workflow, and recent changes
- Scoped rules by file type
- Thin runtime adapters for each AI tool
`init` auto-routes to the right action:

The **structure** is deterministic. The **content** is filled with real knowledge from your repository.
- **Repo has no AI files yet** → installs a fresh canonical `.ai/` layer plus the adapter for the runtime you pick
- **Repo already has AI files** (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, etc.) → runs `standardize` instead, backing up the old files and rewriting the layout

## Install it
At the end, `init` prints a copy-paste-ready prompt for your AI so you can ground the generated context in the real repo.

There are two ways. Pick the one that fits your setup.
### Alternative — let your AI install it

### Option 1 — Let your AI do it (any AI)

Paste this into your AI assistant — Codex, Claude Code, Copilot, Cursor, or any other:
If you prefer, paste this into any AI assistant with local read/write access to the repo:

```
Fetch https://raw.githubusercontent.com/iMark21/agentlayer/main/assistant-installer/PROMPT.md
and follow the complete installation workflow defined there for this repository.
```

The AI fetches the agentlayer spec, **asks you which AI runtime(s) you want**, audits the repo, and generates a grounded `.ai/` layer with real project knowledge — not generic placeholders.

> If your AI cannot fetch URLs directly, download the file first:
> ```bash
> curl -sO https://raw.githubusercontent.com/iMark21/agentlayer/main/assistant-installer/PROMPT.md
> ```
> Then tell your AI: `Read PROMPT.md in this directory and follow the installation workflow.` Delete it when done.

### Option 2 — Use the CLI (deterministic, no AI at install time)

```bash
# Install the CLI (clone somewhere persistent — /tmp gets cleaned and breaks the symlink)
git clone https://github.com/iMark21/agentlayer.git ~/.agentlayer
cd ~/.agentlayer && bash install.sh

# Bootstrap your project
agentlayer install /path/to/your-repo \
--runtimes claude,generic \
--project-type ios
```

The CLI generates the canonical structure deterministically. After install, tell your AI to ground the context files with real repo knowledge:

```
Read CLAUDE.md and the .ai/ layer. The context files are templates —
audit the repository, replace the placeholders with real project knowledge,
and summarize what you found.
```
**Prerequisites for the AI-assisted path:** the assistant must be able to read files in and write files to this repository from your local machine (Codex, Claude Code, Cursor, Copilot CLI, or any other with local filesystem access). Cloud-only chat tools without repo access will not work — use the CLI path above.

Batch or CI installs:
If your AI cannot fetch URLs directly:

```bash
agentlayer install /path/to/your-repo \
--runtimes codex,claude,copilot,cursor,generic \
--project-type android \
--non-interactive --yes
curl -sO https://raw.githubusercontent.com/iMark21/agentlayer/main/assistant-installer/PROMPT.md
```

## Now use it

After install, your AI has context and a structured workflow. Here is what working with it looks like.

### Example: adding a login screen

**Step 1 — Explore the area:**

> Use agent-explore. I need to add a login screen with email and password.

The AI reads `.ai/context/architecture.md`, maps your existing auth code, finds reusable patterns, and reports back — before writing a single line.

**Step 2 — Plan:**

> Use agent-plan. Plan the login screen feature.

You get a file-level plan: which files to create, which to modify, what tests to add, what state pattern to use. Review and approve before any code is written.

**Step 3 — Implement:**

> Use agent-code. Implement the approved plan.
Then ask it: `Read PROMPT.md in this directory and follow the installation workflow.` Delete the file when done.

The AI codes task by task. If a step fails, it stops and reports instead of bulldozing ahead.
## What you get

**Step 4 — Verify:**

> Use agent-verify. Verify the login feature.

Tests run, acceptance criteria are checked, and any residual risk is documented.

The feature is now recorded in `.ai/features/login.md` — so next time anyone (human or AI) touches auth, they have context.

### Example: fixing a bug

> Use agent-fix. The total is not updating when I remove an item from the cart.

The AI loads the project context, finds the root cause, writes a failing test, applies the smallest safe fix, verifies it passes, and records the gotcha in `.ai/context/recent-changes.md`.

### Example: should I refactor this?

> Use agent-spike. Is it worth extracting the payment logic into its own module?

You get a structured analysis: pros, cons, estimated effort, risks, and a recommendation — proceed, pivot, or abandon. No code written, just a decision document.

## What gets installed
A team of agents that follow a structured workflow:

```
.ai/
├── context.md # what the product does and how it is built
├── context/
│ ├── architecture.md # layers, modules, data flow
│ ├── dependencies.md # libraries, SDKs, versions
│ ├── features.md # feature inventory and status
│ ├── repository.md # git workflow, CI, branching
│ └── recent-changes.md # what changed recently, gotchas
├── decision-framework.md # standard patterns for common changes
├── rules/ # guardrails by file type
├── agents/
│ ├── agent-explore.md
│ ├── agent-plan.md
│ ├── agent-code.md
│ ├── agent-verify.md
│ ├── agent-fix.md
│ ├── agent-tech.md
│ ├── agent-spike.md
│ └── agent-context-bootstrap.md
├── skills/ # 4 reusable checklists
├── features/ # memory per completed feature
└── archive/ # past plans and fixes
agent-explore → agent-plan → agent-code → agent-verify
```

Plus a thin adapter at the root for your AI runtime (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursor/rules/agentlayer.mdc`, or `AGENTLAYER.md`).

## Supported runtimes
Plus specialized agents for bug fixes (`agent-fix`), refactors (`agent-tech`), and investigations (`agent-spike`), and four reusable skills (context refresh, feature scaffold, migration audit, context bootstrap).

| Runtime | Adapter generated | Install flag |
| --- | --- | --- |
| Codex | `AGENTS.md` | `--runtimes codex` |
| Claude Code | `CLAUDE.md` | `--runtimes claude` |
| GitHub Copilot | `.github/copilot-instructions.md` | `--runtimes copilot` |
| Cursor | `.cursor/rules/agentlayer.mdc` | `--runtimes cursor` |
| Any other AI | `AGENTLAYER.md` | `--runtimes generic` |
Every installation produces the same deterministic skeleton: 8 agents, 4 skills, 5 context files, scoped rules by file type, and thin adapters for each AI runtime. The **structure** is fixed. The **content** is filled with real knowledge from your repository.

Use `--runtimes all` to generate every adapter. Use `generic` when you want a tool-agnostic setup.
## Using it — example

## Supported project types
Adding a login screen:

| Type | Detected by | Rules generated |
| --- | --- | --- |
| `android` | `settings.gradle`, `AndroidManifest.xml` | Kotlin, Compose |
| `ios` | `.xcodeproj`, `.xcworkspace`, `Package.swift` | Swift, SwiftUI |
| `web` | `package.json`, `pnpm-lock.yaml` | TypeScript, React |
| `backend` | `go.mod`, `Cargo.toml`, `pyproject.toml` | Code, UI |
| `generic` | Fallback | Code, UI |
1. **Explore:** *"Use agent-explore. I need to add a login screen with email and password."* — the AI reads `.ai/context/architecture.md`, maps your existing auth code, and reports back before writing anything.
2. **Plan:** *"Use agent-plan. Plan the login screen feature."* — file-level plan: which files to create, which to modify, which tests to add.
3. **Implement:** *"Use agent-code. Implement the approved plan."* — task by task. Stops and reports if a step fails.
4. **Verify:** *"Use agent-verify. Verify the login feature."* — runs tests, checks acceptance criteria, documents residual risk.

The CLI auto-detects the project type from the repo structure. Override with `--project-type`.
The feature is recorded under `.ai/features/login.md` so the next session already has context.

## The core idea
For bug fixes: *"Use agent-fix. The total is not updating when I remove an item from the cart."*
For refactor decisions: *"Use agent-spike. Is it worth extracting the payment logic into its own module?"* — returns a decision document, no code.

The system is runtime-agnostic. agentlayer works on any tech project if you define these five things well:
## Supported runtimes and project types

1. Product context and architecture
2. Precise rules by file type or module
3. A decision framework for common changes
4. Specialized agents or flows by task type
5. Useful memory of what has already been done
- Runtimes: Codex, Claude Code, GitHub Copilot, Cursor, or a tool-agnostic `AGENTLAYER.md` for any other AI.
- Project types (auto-detected): Android, iOS, web, backend, or generic fallback.

The stack, the language, and the AI runtime can all change. These five pieces are what make a repository legible to any assistant from the first session.
See [MANUAL.md](MANUAL.md) for the full reference — every command, every flag, every adapter format, every rule generated.

## Read more

- [MANUAL.md](MANUAL.md) — Full reference: all commands, flags, workflows, and advanced usage
- [CONTRIBUTING.md](CONTRIBUTING.md) — How to contribute
- [CHANGELOG.md](CHANGELOG.md) — Version history
- [MANUAL.md](MANUAL.md) — full reference: commands, flags, workflows, generated structure
- [CHANGELOG.md](CHANGELOG.md) — version history
- [CONTRIBUTING.md](CONTRIBUTING.md) — how to contribute
Loading
Loading