Project Init

Project Init

You are Cortex, initializing context for a new or existing project. Your job is to scan the project's code and resources (locally and on any registered remote machines), read core documentation to understand what the project does, then generate structured context files so future Cortex sessions can quickly pick up where work left off.

Project info

$ARGUMENTS

The user should provide: project name, code location (which machine, what path), and optionally a brief description of the project's goal.

If critical info is missing, ask the user before proceeding.

Step 1: Scan the Project

Inspect the project's code and resources. If multiple machines host parts of the project, use Agent subagents for parallel exploration.

• Directory structure: ls -la, tree -L 2 (or equivalent) to understand organization
• Key files: README, config files, dependency manifests (requirements.txt / pyproject.toml / package.json / Cargo.toml / go.mod / Makefile), entry-point scripts
• Git state: current branch, recent commits (git log --oneline -10), remotes
• Stack: identify language, framework, runtime, key dependencies
• Data paths: where input data, generated artifacts, and outputs live
• Core documentation: read README, design docs, or any documentation that explains what the project is about. This is critical for understanding the project's goal and approach.

Step 2: Create Context Structure

Create the project directory and files under context/projects//:

CORTEX.md (required) — Project index

This is the entry point for future sessions. Must include:

• One-line project description
• Approval rules for any sensitive deliverables (production code, customer-facing docs, etc.)
• File list table (all files in this directory)
• Quick lookup section (what to find where)
• Project location map: detailed table of paths on each machine, covering code, data, generated artifacts, docs, results, etc.

# / Index

[One-line description]. [Optional: target audience or deliverable].

## File List

| File | Type | Purpose |
|------|------|---------|
| STATUS.md | Overwrite | Current project state snapshot |
| experiments/ | Atomic file | One EXP-NNN.md per experiment (YAML frontmatter + body), index.md auto-generated |
| knowledge/ | Atomic file | One K-NNN.md per knowledge entry, index.md auto-generated |
| patterns/ | Atomic file | Cross-experiment patterns, index.md auto-generated |
| _meta/ | Auto | access-log.jsonl (hook tracks access records) |
| mission.md | Stable | Goals and success conditions |

## Quick Lookup

- [topic] → `[file]` § [section]
- ...

## Project Component Locations

### [machine1] (`ssh ...`)

| Path | Content | Description |
|------|---------|-------------|
| ... | ... | ... |

### [machine2] (`ssh ...`)

| Path | Content | Description |
|------|---------|-------------|
| ... | ... | ... |

STATUS.md (required) — Current state snapshot

# [Project Name] — STATUS

**Last updated**: [date]

## Current State

**Phase**: [phase]
**Status**: [status]

- [key facts about current state]

## Key Metrics

[results table if available]

## Machine Status

| Machine | Status | Content |
|---------|--------|---------|
| ... | ... | ... |

experiments/ (required) — Experiment records (atomized, DR-0007)

Create the experiments/ directory. If the project has existing experiments, create individual EXP-NNN.md files with YAML frontmatter (see .claude/rules/experiment-format.md for format). Otherwise create an empty directory. Run cd agent-server && node --import tsx src/memory-index-regen.ts to generate index.md.

knowledge/ (required) — Technical knowledge (atomized, DR-0007)

Create the knowledge/ directory. Capture technical details as individual K-NNN.md files with YAML frontmatter:

• Architecture details (modules, interfaces, data flow)
• Data format (directory structure, file types, schema)
• Runtime / deployment flow (communication protocols, ports, services)
• Configuration (config files, env vars, key parameters)
• Environment setup (runtime, key dependencies)
• Known pitfalls or quirks

patterns/ and _meta/ (required) — Supporting dirs

Create empty patterns/ directory and _meta/ directory with empty access-log.jsonl.

mission.md (required) — Goal and success criteria

Draft from README, design doc, or user description. Mark as draft for user review.

roadmap.md (optional) — Only if clear milestones exist

Skip for projects already in late-stage delivery. Create only when the project has clear future milestones with testable verification conditions.

Step 3: Update Indexes

1. Add the project to context/projects/CORTEX.md project list table
2. Add the project to context/OVERVIEW.md

Step 4: Commit

git add context/projects// context/projects/CORTEX.md context/OVERVIEW.md
git commit -m "project-init: add  ()"

Step 5: Report

Output a structured summary:

• What the project is about (from README / docs)
• Location map (which machine has what)
• Key technical details (architecture, data, current state)
• Files created

Principles

• Read the README and core docs first — understanding the project is prerequisite to useful context files
• CORTEX.md is the most important file — it's the entry point for all future sessions
• Location map must be exhaustive — every relevant path on every machine
• Auto-generated content is clearly marked — the user owns the final version
• mission.md is a draft until the user confirms
• If the project directory already has context files, warn the user instead of overwriting
• If SSH fails or a path doesn't exist, report the failure clearly

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fangxm233
• Source: fangxm233/cortex-agent
• License: MIT

Install and usage instructions live in the source repository linked above.