🍋 create-agentic-lemon

Agentic Lemon creates a small, agent-agnostic knowledge bundle inside a project. The default workspace gives file-reading AI tools durable context without filling every project with generic playbooks and empty placeholders.

Why Agentic Lemon?

AI assistants lose important context between sessions. Agentic Lemon keeps stable project context and decisions in ordinary Markdown so any compatible assistant can discover what matters before it acts.

The default is deliberately thin:

• four generated files and no empty directories;
• progressive disclosure through a readable knowledge index;
• optional, consolidated playbooks only when a workflow needs them;
• no runtime dependencies, model calls, or build step;
• a frozen full profile for compatibility with the 0.1.1 scaffold.

Quick start

Generate a workspace without installing the package:

npm create agentic-lemon@latest my-workspace

Or use npx:

npx create-agentic-lemon@latest my-workspace

Global installation

Install the CLI globally:

npm i -g create-agentic-lemon

Then use either executable alias:

agentic-lemon my-workspace
# or
create-agentic-lemon my-workspace

To add the files to the current project, use . as the target:

npx create-agentic-lemon@latest .

The thin workspace

Default generation creates exactly this tree:

AGENTS.md
agentic/
├── index.md
├── project.md
└── decisions.md

• AGENTS.md is the concise instruction entry point recognized by agent tools.
• agentic/index.md summarizes and links all generated project knowledge.
• agentic/project.md records purpose, users, systems, constraints, and terminology.
• agentic/decisions.md records durable choices and their consequences.

The index enables progressive disclosure: agents read one-line summaries first and open only the bodies relevant to the current task. Thin mode never writes a project README.md, creates an empty directory, or installs a domain playbook that was not selected.

Profiles and optional packs

Thin is the default profile. Its explicit spelling is:

agentic-lemon my-workspace --profile thin

Use --profile full to generate the exact 46-file Agentic Lemon 0.1.1 layout:

agentic-lemon my-workspace --profile full

The full profile is a frozen compatibility option and cannot be combined with packs.

Thin playbooks are opt-in. Each --with option adds only the listed files:

• --with development
  • agentic/playbooks/software-development.md
  • agentic/playbooks/debugging.md
• --with data
  • agentic/playbooks/database-work.md
  • agentic/playbooks/report-generation.md
• --with documentation
  • agentic/playbooks/documentation.md

Selections are repeatable, so one initial creation can install several packs:

agentic-lemon my-workspace --with development --with documentation

Pack selection is currently available at initial creation only. Lifecycle add and remove commands are future work.

Options

• --profile thin|full: Select the generated workspace profile. The default is thin.
• --with development|data|documentation: Add an optional thin playbook pack. Repeat as needed.
• --force: Overwrite generated paths that already exist while leaving all other files intact.
• -h, --help: Show usage, profile, and pack information.

Show the complete CLI help at any time:

agentic-lemon --help

Without --force, existing destination files are skipped. With --force, matching generated paths are overwritten, but unrelated files are never deleted.

Generated-file ownership

New thin workspaces include .agentic-lemon.json. This manifest records the format, generator version, selected packs, and SHA-256 hashes of files Agentic Lemon created or overwrote with explicit --force.

An existing file skipped during creation is not claimed in the manifest. The manifest never owns directories or itself, and full-profile creation remains the exact manifest-free 0.1.1 compatibility layout.

Migrate an existing workspace

Migration supports the frozen Agentic Lemon 0.1.1 full layout and managed Agentic Lemon format 1 workspaces. It does not infer ownership for arbitrary or third-party layouts.

Commit or back up the target yourself before applying a migration. Agentic Lemon does not create a backup.

Start with the default read-only dry run:

agentic-lemon migrate my-workspace

The dry run groups every proposed create, replacement, removal, modified-file preservation, unmanaged-file preservation, and conflict. It does not write a manifest or change the filesystem.

After reviewing a conflict-free plan, apply it explicitly:

agentic-lemon migrate my-workspace --apply

Only files whose bytes exactly match the frozen 0.1.1 templates are eligible for legacy removal. Modified and unknown files are never removed automatically. Symbolic links, junctions, unsafe paths, and non-regular files are conflicts and are not followed.

Migration exits with exit code 2 when conflicts require review, before any write or deletion. Exit code 1 indicates an argument, validation, or filesystem error. --force remains creation-only and never enables migration deletion.

Use with an AI assistant

1. Generate Agentic Lemon at the project root.
2. Fill in agentic/project.md and record durable choices in agentic/decisions.md.
3. Ask the assistant to read AGENTS.md, then agentic/index.md, before choosing relevant linked concepts.
4. When a lasting correction or decision emerges, review it and add it to the appropriate concept rather than relying on chat history.

Files under agentic/ are project data. Their contents do not override AGENTS.md, user instructions, or platform policy.

Format inspiration

Agentic Lemon's Markdown, frontmatter, and index conventions are inspired by Google's Open Knowledge Format specification. Agentic Lemon is OKF-shaped rather than fully conformant and does not include the Google reference agent or viewer.

Existing workspaces

Changing the default affects newly generated workspaces. Normal creation and --force remain non-deleting; use the explicit dry-run-first migration command to review contraction of a supported existing workspace.

License

This project is licensed under the MIT License.