Project Structure & Session Management

Author: skew202 Updated: 2026-01-03

The Philosophy

"Every project is a research endeavor. Every session builds on the last. Every AI agent needs proper context."

My monorepos contain everything: research, plans, journals, and all AI agent configurations. This ensures session continuity and optimal agent context.

Monorepo Structure

project-name/
├── README.md                    # Project overview + quick start
├── ROADMAP.md                   # Project roadmap with milestones
├── .github/                     # GitHub-specific (CI/CD, templates)
│
├── research/                    # █ Meta-research artifacts
│   ├── 01-sota-discovery.md     # Grok: What's SOTA
│   ├── 02-first-principles.md   # Opus: First principles analysis
│   ├── 03-critique-synthesis.md # Multi-agent critique
│   ├── 04-deep-research.md      # Perplexity: Deep research
│   ├── 05-project-guide.md     # Opus: Project guide synthesis
│   └── 06-standards.md          # Opus: Engineering standards
│
├── docs/                        # █ Living documentation
│   ├── architecture/            # C4 diagrams
│   │   ├── context.puml
│   │   ├── containers.puml
│   │   ├── components.puml
│   │   └── code.puml
│   ├── api/                     # API documentation
│   ├── guides/                  # User guides
│   └── operations/              # Runbooks
│
├── archive/                     # █ Session journals (by datetime)
│   ├── 2026-01-03-session-1.md
│   ├── 2026-01-03-session-2.md
│   └── 2026-01-04-session-1.md
│
├── .ai/                         # █ AI Agent Configurations
│   ├── claude/                  # Claude Code config
│   │   ├── CLAUDE.md            # Project context for Claude
│   │   └── settings.json        # Claude settings
│   ├── cursor/                  # Cursor config
│   │   ├── .cursorrules         # Cursor rules
│   │   └── .cursorrules-ops     # Cursor rules for ops
│   ├── antigravity/             # Antigravity config
│   │   ├── workflows/           # Workflows
│   │   ├── slash-commands/      # Slash commands
│   │   └── skills/              # Skills
│   ├── mcp/                     # Model Context Protocol
│   │   └── servers.json         # MCP servers
│   ├── hooks/                   # Pre/post hooks
│   ├── lsp/                     # LSP configuration
│   └── tools/                   # Tool permissions
│
├── src/                         # Application source
├── tests/                       # Test files
├── k8s/                         # Kubernetes manifests
└── scripts/                     # Utility scripts

The AI Directory (`.ai/`)

This is the brain of the project - all AI agent configurations live here.

Claude Code Configuration

.ai/claude/
├── CLAUDE.md                    # Main context file
├── settings.json                # Claude settings
└── project-context.json         # Additional context

CLAUDE.md Template:

# Project: [Project Name]

## Overview
[2-3 sentence project description]

## Tech Stack
- Language: [Language]
- Framework: [Framework]
- Database: [Database]
- Deployment: [Kubernetes / ArgoCD]

## Architecture
[C4 context summary]

## Key Design Decisions
1. [Decision 1]: [Rationale]
2. [Decision 2]: [Rationale]

## Project Guide Reference
See: `research/05-project-guide.md`

## Standards Reference
See: `research/06-standards.md`

## Current Work
- Feature: [Current feature]
- Status: [In progress / Blocked / Review]
- Next steps: [What to do next]

## Session Context
Last session: `archive/2026-01-03-session-X.md`

Cursor Configuration

.ai/cursor/
├── .cursorrules                 # Main cursor rules
├── .cursorrules-ops             # Rules for infrastructure work
└── .cursorignore                # Files to ignore

.cursorrules Template:

You are an expert [language] engineer working on [project name].

PROJECT CONTEXT:
[Relevant context from CLAUDE.md]

CODE STYLE:
- Follow patterns in `src/[module]/`
- Use [formatter] for formatting
- No TODOs - implement or file issue

WORKFLOW:
1. Read existing code before changing
2. Follow established patterns
3. Write tests for new code
4. Run tests before claiming done

ARCHITECTURE:
- [Key architectural principle 1]
- [Key architectural principle 2]

FILES TO REFERENCE:
- Architecture: docs/architecture/
- Standards: research/06-standards.md
- Project Guide: research/05-project-guide.md

Antigravity Configuration

.ai/antigravity/
├── workflows/                   # Automation workflows
│   ├── setup-feature.yml
│   ├── deploy.yml
│   └── test.yml
├── slash-commands/              # Custom slash commands
│   ├── architect.md
│   ├── implement.md
│   └── review.md
└── skills/                      # Custom skills
    ├── code-review-skill.md
    └── test-generator-skill.md

Example Slash Command (implement.md):

---
description: Implement a feature from project guide
---

Implement the feature described in the project guide.

Reference: research/05-project-guide.md
Standards: research/06-standards.md
Architecture: docs/architecture/

Follow the established patterns in src/.

Generate tests as you go (TDD).

MCP Servers Configuration

// .ai/mcp/servers.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"]
    }
  }
}

Hooks Configuration

.ai/hooks/
├── pre-commit.sh               # Run before commit
├── pre-push.sh                 # Run before push
├── pre-session-start.sh        # Run before starting session
└── post-session-end.sh         # Run after ending session

pre-session-start.sh:

#!/bin/bash
echo "🚀 Starting session..."

# Load last session journal
LAST_SESSION=$(ls -t archive/*.md | head -1)
echo "📚 Last session: $LAST_SESSION"

# Check for uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
  echo "⚠️  Uncommitted changes detected"
fi

# Run tests
echo "🧪 Running tests..."
npm test || echo "⚠️  Tests failing"

echo "✅ Session ready"

Session Management

Session Start Ritual

# 1. Open project
cd project-name/

# 2. Start session hook
.ai/hooks/pre-session-start.sh

# 3. Read last session journal
LAST_SESSION=$(ls -t archive/*.md | head -1)
cat "$LAST_SESSION"

# 4. Load context files
cat research/05-project-guide.md
cat research/06-standards.md
cat docs/README.md

# 5. Start Claude Code / Cursor / etc.

Session End Ritual

# 1. Run session end hook
.ai/hooks/post-session-end.sh

# 2. Create session journal
SESSION_FILE="archive/$(date +%Y-%m-%d-session-X.md"

# 3. Document session
cat > "$SESSION_FILE" << EOF
# Session: $(date +%Y-%m-%d) - Session X

## Context
- Previous session: [link to last session]
- Branch: $(git branch --show-current)
- Commit: $(git rev-parse --short HEAD)

## Goal
[What we set out to do]

## Work Done
### 1. [Task 1]
- Done: [What was completed]
- Files: [Files changed]
- Commit: [Commit hash]

### 2. [Task 2]
- Done: [What was completed]
- Files: [Files changed]
- Commit: [Commit hash]

## Decisions Made
1. [Decision 1]: [Rationale]
2. [Decision 2]: [Rationale]

## Problems Encountered
- [Problem 1]: [How we solved it]
- [Problem 2]: [How we solved it]

## Next Steps
1. [Next step 1]
2. [Next step 2]

## Context for Next Session
- Pick up from: [file/function/feature]
- Known issues: [List]
- Open questions: [List]
EOF

# 4. Commit if needed
git add -A && git commit -m "docs: session journal $(date +%Y-%m-%d)"

Session Journal Template

# Session: YYYY-MM-DD - Session N

## Metadata
- **Date:** YYYY-MM-DD
- **Time:** HH:MM - HH:MM (duration)
- **Previous Session:** [link]
- **Branch:** `feature/name`
- **Starting Commit:** `abc123`
- **Ending Commit:** `def456`

---

## Context Carryover

### From Last Session
[Summary of what was done last time]

### Current State
- Feature: [What we're working on]
- Status: [In progress / Blocked / Review]
- blockers: [If any]

---

## Session Goal
[What we set out to accomplish this session]

---

## Work Completed

### Task 1: [Task Name]
**Status:** ✅ Done / ⚠️ Partial / ❌ Blocked

**What was done:**
- [Accomplishment 1]
- [Accomplishment 2]

**Files changed:**
- `path/to/file1.ts` - [Change summary]
- `path/to/file2.ts` - [Change summary]

**Commits:**
- `abc123` - feat: implement feature X
- `def456` - fix: handle edge case

**Tests:**
- Unit: [Status]
- Integration: [Status]
- E2E: [Status]

### Task 2: [Task Name]
**Status:** ...

---

## Decisions Made

### Decision 1: [Title]
- **Context:** [Problem/Question]
- **Options Considered:**
  - Option A: [Pros/Cons]
  - Option B: [Pros/Cons]
- **Decision:** [What we chose]
- **Rationale:** [Why]
- **Impact:** [What this affects]

### Decision 2: [Title]
...

---

## Problems Encountered

### Problem 1: [Title]
- **Issue:** [What went wrong]
- **Attempted Solutions:**
  - Tried: [Solution 1] - Result: [Failed/Partial]
  - Tried: [Solution 2] - Result: [Success]
- **Final Solution:** [How we fixed it]
- **Lessons Learned:** [What to remember]

### Problem 2: [Title]
...

---

## Agent Interactions

### Grok - Brainstorming
**Prompt:** What we asked
**Output:** Key ideas captured
**Used:** Which ideas we implemented

### Opus - Planning
**Prompt:** What we asked
**Output:** Plan generated
**Used:** How it guided implementation

### Sonnet - Implementation
**Prompt:** What we asked
**Output:** Code generated
**Changes:** Manual changes made (why)

### Gemini - Documentation
**Prompt:** What we asked
**Output:** Docs generated
**Review:** Any corrections needed

### GLM - Validation
**Prompt:** What we asked
**Output:** Issues found
**Fixes:** Applied fixes

---

## Research Notes

### SOTA Discovery
- New papers found: [List]
- New tools discovered: [List]
- Worth investigating: [What to look into]

### Standards Updates
- New best practices: [List]
- Deprecated patterns: [List]
- Need to update: [What to change]

---

## Next Session

### Pick Up From
- File: `path/to/file.ts`
- Function: `functionName`
- Line: ~123

### TODO List
- [ ] [Task 1] - Priority: High
- [ ] [Task 2] - Priority: Medium
- [ ] [Task 3] - Priority: Low

### Known Issues
1. [Issue 1]: [Workaround if any]
2. [Issue 2]: [Workaround if any]

### Open Questions
1. [Question 1]: [How to find answer]
2. [Question 2]: [How to find answer]

### Branches
- Active: `feature/name` - [Purpose]
- Stale: `old-feature` - [Why it's stale]

---

## Session Metrics

- **Duration:** X hours
- **Files changed:** N
- **Lines added:** N
- **Lines removed:** N
- **Commits:** N
- **Tests run:** N
- **Tests passing:** N/N

---

## Files to Reference Next Time

1. `research/05-project-guide.md` - Project guide
2. `research/06-standards.md` - Engineering standards
3. `docs/architecture/components.puml` - Architecture
4. `src/path/to/file.ts` - Current work

README.md Structure

# Project Name

## Quick Start
[Get running in 5 minutes]

## Overview
[What this project does]

## Architecture
[Link to architecture docs]

## Development
[How to set up dev environment]

## Session Continuity
For AI agents, reference:
- `.ai/CLAUDE.md` - Main context file
- `archive/[latest-session].md` - Last session journal
- `research/05-project-guide.md` - Project guide

## Roadmap
See [ROADMAP.md](ROADMAP.md)

## Contributing
[How to contribute]

## License
[License info]

ROADMAP.md Structure

# Roadmap

## Completed ✅
- [x] Milestone 1 (YYYY-MM-DD)
- [x] Milestone 2 (YYYY-MM-DD)

## In Progress 🚧
- [ ] Milestone 3 (YYYY-MM-DD)
  - [x] Subtask 1
  - [ ] Subtask 2
  - [ ] Subtask 3

## Planned 📋
- [ ] Milestone 4 (YYYY-Q2)
- [ ] Milestone 5 (YYYY-Q3)

## Backlog 📝
- [ ] Feature A
- [ ] Feature B
- [ ] Feature C

## Research Needed 🔬
- [ ] Research topic 1
- [ ] Research topic 2

Tool Permissions (.ai/tools/)

// .ai/tools/permissions.json
{
  "allowedTools": {
    "bash": {
      "enabled": true,
      "commands": [
        "ls", "cat", "grep", "find",
        "git", "npm", "node", "python",
        "docker", "kubectl"
      ]
    },
    "editor": {
      "enabled": true,
      "allowWrite": true,
      "allowedPaths": ["src/", "tests/", "docs/"]
    },
    "browser": {
      "enabled": true,
      "allowedDomains": [
        "github.com",
        "npmjs.com",
        "docs.anthropic.com"
      ]
    }
  }
}

LSP Configuration (.ai/lsp/)

// .ai/lsp/config.json
{
  "languageServers": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "filetypes": ["typescript", "tsx"]
    },
    "python": {
      "command": "pyright-langserver",
      "args": ["--stdio"],
      "filetypes": ["python"]
    },
    "gopls": {
      "command": "gopls",
      "filetypes": ["go"]
    }
  }
}

Quick Start Scripts

#!/bin/bash
# scripts/start-session.sh

echo "🚀 Starting AI-Native Session..."

# Run pre-session hook
.ai/hooks/pre-session-start.sh

# Show last session
LAST_SESSION=$(ls -t archive/*.md | head -1)
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📚 LAST SESSION:"
cat "$LAST_SESSION"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

# Show current context
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📖 PROJECT GUIDE:"
head -50 research/05-project-guide.md
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

# Open IDE
echo ""
echo "Opening Claude Code..."
claude-code

# When done, run:
# .ai/hooks/post-session-end.sh

Directory Initialization Script

#!/bin/bash
# scripts/init-ai-project.sh

PROJECT_NAME=$1

mkdir -p "$PROJECT_NAME"
cd "$PROJECT_NAME"

# Create directory structure
mkdir -p research docs/architecture docs/api docs/guides docs/operations
mkdir -p archive
mkdir -p .ai/claude .ai/cursor .ai/antigravity/{workflows,slash-commands,skills}
mkdir -p .ai/{mcp,hooks,lsp,tools}
mkdir -p src tests k8s scripts

# Create initial files
touch README.md ROADMAP.md
touch research/{01-sota-discovery.md,02-first-principles.md,03-critique-synthesis.md,04-deep-research.md,05-project-guide.md,06-standards.md}
touch .ai/claude/CLAUDE.md
touch .ai/cursor/.cursorrules
touch .ai/mcp/servers.json

# Make hooks executable
chmod +x .ai/hooks/*.sh

echo "✅ AI-Native project initialized: $PROJECT_NAME"

Summary

Your Project Structure Signals

Aspect	What It Shows
Monorepo	Professional project organization
Research/	You understand before building
Archive/	Session continuity - builds on previous work
.ai/	AI-native workflow, optimized for agents
Multiple IDE configs	Tool-agnostic, uses best tool for job
Session journals	Rigorous documentation, reproducible sessions
Hooks	Automation, consistency

The Signal

"I don't just code. I maintain a living research archive, optimize my AI agents' context, and ensure every session builds on the last. My projects are knowledge repositories, not just codebases."

License: MIT

skew202/project-structure.md

Select an option

No results found

Select an option

No results found

Project Structure & Session Management

The Philosophy

Monorepo Structure

The AI Directory (`.ai/`)

Claude Code Configuration

Cursor Configuration

Antigravity Configuration

MCP Servers Configuration

Hooks Configuration

Session Management

Session Start Ritual

Session End Ritual

Session Journal Template

README.md Structure

ROADMAP.md Structure

Tool Permissions (.ai/tools/)

LSP Configuration (.ai/lsp/)

Quick Start Scripts

Directory Initialization Script

Summary

Your Project Structure Signals

The Signal

skew202/project-structure.md

Project Structure & Session Management

The Philosophy

Monorepo Structure

The AI Directory (.ai/)

Claude Code Configuration

Cursor Configuration

Antigravity Configuration

MCP Servers Configuration

Hooks Configuration

Session Management

Session Start Ritual

Session End Ritual

Session Journal Template

README.md Structure

ROADMAP.md Structure

Tool Permissions (.ai/tools/)

LSP Configuration (.ai/lsp/)

Quick Start Scripts

Directory Initialization Script

Summary

Your Project Structure Signals

The Signal

The AI Directory (`.ai/`)