Limina

Limina is a small research-first agent template for Claude Code and Codex. It keeps durable evidence in kb/ without dragging a large operational ledger into every session. Projects also get a ready-to-send /goal command for long-running continuity.

Workflow

Step 1: Introduce Limina

Before asking setup questions, explain:

What you're setting up: an autonomous research project with a persistent knowledge base, a narrow active-state file, and a required H -> E -> F evidence flow.

The agent can work across long sessions, but the always-on context stays small: mission brief, active state, and only the relevant artifacts for the current step. Claude Code and Codex are both supported; both get a generated /goal.

Step 2: Ask for a project name

Default: limina-research.

Step 3: Clone the template

Clone https://github.com/theam/limina.git into ./<project-name>/, then remove .git and initialize a fresh repo.

Step 4: Check prerequisites

Verify that python3, git, and either Claude Code or Codex are available.

The template's core scripts use the Python standard library and do not require a package install. If the user also wants to develop Limina itself or run the complete repository test suite and has uv, install the locked development environment:

uv sync --locked --dev

Step 5: Define the mission

Ask for:

1. objective
2. context or baseline
3. success criteria
4. resources and boundaries
5. blocked stop condition

Use concise examples and keep the prompt focused on the research problem, not on project administration.

Step 6: Write the mission brief

Create kb/mission/CHALLENGE.md with:

---
aliases: ["CHALLENGE"]
type: mission
---

# Research Mission

## Objective

<objective>

## Context

<context or "No additional context provided.">

## Success Criteria

<success criteria>

## Resources & Boundaries

<allowed resources, budget, data, tools, and off-limits areas>

## Constraints

- Ask when blocked on access, trust in the evaluation, or strategic decisions.
- Persist durable evidence in `kb/`.
- Keep active state in `kb/ACTIVE.md`.

## Blocked Stop Condition

<when the agent should stop and ask for help>

## Links

- Active State: [[ACTIVE]]
- Dashboard: [[DASHBOARD]]

Create kb/ACTIVE.md with:

---
aliases: ["ACTIVE"]
type: active-state
---

# Active State

## Current Objective

Initialize the research loop for the mission.

## Next Step

Read the mission and form the first concrete research question.

## Blocker

None.

## Links

- Mission: [[CHALLENGE]]

Step 7: Generate the long-running Goal

Run:

python3 scripts/generate_goal.py --write

If it fails, fix the missing CHALLENGE.md fields and run it again. The generated kb/mission/GOAL.md provides the ready-to-send /goal command for Claude Code and Codex.

Step 8: Validate and commit

Run:

python3 scripts/kb_validate.py

Then commit:

git add -A
git commit -m "Initialize Limina research project"

Step 9: Tell the user how to start

Tell the user:

Your research project is ready at ./<project-name>/.

Open Claude Code in the project directory:

cd <project-name> && claude

Then send the /goal command from kb/mission/GOAL.md. Or open the folder in Codex and send the same command there.

The runtime loads the mission brief and active state at startup. Hooks enforce H -> E -> F, validate kb writes, and run a final kb validation before stop.

To install the bundled repo-local companion skills (experiment-rigor, exploratory-sota-research, research-devil-advocate, build-maintainable-software) into Claude Code and/or Codex from inside the project repo, run:

bash scripts/install_skills.sh