AndSoOn

A Git-native, AI-first project management system where the source of truth is markdown files in your repository.

Philosophy

Project management tools often create a barrier between your code and your planning. AndSoOn takes a different approach: your project management system IS your Git repository. Tasks are markdown files with YAML frontmatter. Status is folder structure. History is Git log.

This design philosophy creates three powerful properties:

1. AI-Native: Markdown + frontmatter is the natural language of LLMs. Claude Code can read, create, and update tasks as easily as you can.
2. Transparent: Everything is plain text. Grep it, diff it, version it. No database, no proprietary formats.
3. Flexible: No imposed workflows. Organize tasks however you want. Add custom fields. Let Git history document the reasoning.

How It Works

Data Structure

your-project/
├── tasks/
│   ├── backlog/
│   │   └── 01-implement-feature.md
│   ├── in-progress/
│   │   └── 02-fix-bug.md
│   └── done/
│       └── 03-setup-ci.md

Each task is a markdown file with frontmatter:

---
title: Implement CLI core commands
created: 2025-12-28
tags: [cli, development]
assignee: mason
priority: high
---

## Description

Implement the core CLI commands for AndSoOn in Go.

## Commands to Implement

- create: Create new tasks
- list: Filter and display tasks
- move: Change task status
...

Status is location. Moving a file from backlog/ to in-progress/ updates its status. Git tracks when and why it moved.

Components (Monorepo)

AndSoOn is organized as a Turborepo monorepo with three main applications:

• CLI (apps/cli): Go binary for creating, updating, and managing tasks ⚡ V1 Focus
• MCP Server (apps/mcp): Claude Code integration for AI-assisted project management 🚧 Coming Soon
• Web UI (apps/web): Read-only visualization (Kanban, lists, Gantt charts) 🚧 Coming Soon

Why This Approach?

For Developers

• Use tools you already know: Git, grep, your favorite editor
• Offline-first: No server, no database, no internet required
• Scriptable: Tasks are just files—pipe them through jq, awk, whatever
• Version control built-in: See who changed what and when
• Merge conflicts are rare: Each task is a separate file

For AI Collaboration

• LLMs read markdown natively: No API translation layer needed
• Context is grep-able: Claude can search your tasks like you do
• Batch operations are simple: Update 20 tasks? Just edit 20 files.
• Transparent reasoning: Git commits show why tasks changed

For Teams

• Standard Git workflows: PRs for planning changes, branches for proposals
• No vendor lock-in: It's just markdown files
• Custom fields without migrations: Add any frontmatter field you want
• Audit trail for free: Git log shows the full project history

Current Status

We're dog-fooding AndSoOn to build itself! Check the example/aso/cli/ folder to see real task examples.

V1 Status: CLI is functional with core commands implemented.

Quick Start

# 1. Initialize a new project
cd your-project
aso init

# 2. Create your first task
aso create "Set up CI pipeline"

# 3. Browse tasks interactively
aso browse

Running aso browse in an uninitialized directory will prompt you to initialize.

CLI Usage

# Initialize a new project
$ aso init
✓ Project initialized successfully

Created:
  • .aso.yaml
  • tasks/backlog/
  • tasks/in-progress/
  • tasks/done/

# Create a new task
$ aso create "Implement search command"
📝 Created: tasks/backlog/07-implement-search.md

# List all tasks
$ aso list
BACKLOG (5 tasks)
  01-implement-cli-core.md          [cli, development]
  02-cli-interactive-mode.md        [cli, ux]
  ...

# Move task to in-progress
$ aso move 01-implement-cli-core in-progress
✓ Moved to tasks/in-progress/01-implement-cli-core.md

# Interactive mode (asks questions when context is missing)
$ aso create
? Task title: Add Git auto-commit
? Priority: (high/medium/low) medium
? Assign to: (default: mason) mason
? Tags: cli, git, automation
📝 Created: tasks/backlog/08-git-auto-commit.md

Frontmatter Schema

AndSoOn uses a flexible schema approach. There are no strict rules—add whatever fields make sense for your project.

Suggested Core Fields

title: string          # Task title (suggested)
created: date         # Creation timestamp (auto-generated)
updated: date         # Last update (auto-generated)
tags: array           # Categorization tags
assignee: string      # Person assigned
priority: enum        # high | medium | low
status: inferred      # Derived from folder location

Custom Fields Welcome

Add any fields you need:

estimate: 3 days
sprint: 2025-Q1-S3
blocked_by: [task-12, task-15]
customer: acme-corp

The CLI will validate common fields but won't complain about custom ones.

Roadmap

V1: CLI Foundation

• Project concept and architecture
• Monorepo setup
• Core commands: create, list, move, update, search, assign, view
• Project initialization (aso init) with first-run TUI modal
• Interactive TUI browser (aso browse)
• Frontmatter validation
• AI-enhanced task creation (via Claude CLI)

V2: AI Integration

• MCP server for Claude Code
• Natural language task creation
• AI-powered project insights
• Batch operations through Claude

V3: Visualization

• Read-only web UI
• Kanban board view
• List and Gantt chart views
• Live updates via file watching

Installation

Homebrew (macOS and Linux)

brew tap masonkmeyer/andsoon
brew install aso

Manual Installation

Download the latest release for your platform from the Releases page, extract the archive, and move the aso binary to a directory in your PATH.

From Source

git clone https://github.com/masonkmeyer/AndSoOn.git
cd AndSoOn/apps/cli
go build -o aso .

Contributing

This project is in early development. We're focused on getting V1 (CLI) right before expanding scope.

Interested in contributing? Check out the tasks in example/aso/cli/backlog/ to see what's planned.

Design Principles

1. Git is the database: Leverage existing tools rather than reinventing them
2. Markdown is the API: Both humans and AIs can read and write it
3. Flexibility over enforcement: No rigid workflows, just conventions
4. Transparency over abstraction: Plain text files you can grep and diff
5. Offline over online: No server required for core functionality

FAQ

Q: Why not just use GitHub Issues? A: GitHub Issues are great but not designed for AI interaction, offline work, or custom workflows. AndSoOn gives you full control and keeps everything in your repo.

Q: What about conflicts when multiple people edit tasks? A: Each task is a separate file, so conflicts are rare. When they happen, Git handles them like any other merge conflict.

Q: Can I use this with existing tools? A: Absolutely! The markdown files are just files. Parse them with any tool you want. The Web UI and MCP server are optional conveniences.

Q: Why Go for the CLI? A: Cross-platform single binary distribution, fast performance, excellent standard library for file operations and CLI building.

Q: Is the folder structure required? A: The backlog/in-progress/done structure is the reference implementation, but you can organize folders however you want. The CLI will adapt to your structure.

Q: What does .aso.yaml contain? A: The configuration file specifies where your tasks live. By default: tasks_dir: ./tasks. This lets you place the config at your repo root while storing tasks in a subdirectory.

License

MIT License - see LICENSE for details.