consigliere

README

Consigliere

Your trusted advisor for managing knowledge, projects, and ideas — powered by AI.

---

🇮🇹 In Italian, a consigliere (kon-seel-YEH-reh) is a trusted counselor — the person you turn to before making a decision. Consigliere plays that role for your AI-assisted workflow: it organizes your thinking, tracks your projects, remembers what you've learned, and makes sure nothing falls through the cracks.

---

🤔 Why Consigliere?

Most developers accumulate knowledge across dozens of tools — Notion pages, Slack threads, scattered markdown files, browser bookmarks, mental notes. When you sit down with an AI coding assistant, all that context is invisible to it.

Consigliere solves this by giving your AI assistant a structured knowledge base it can actually read:

• 🧠 Start a session and your AI already knows your active projects, open decisions, and areas of responsibility
• 💡 Capture ideas on the fly — they flow through a lifecycle from raw thought to active project
• 📝 Never lose context — session notes, technical findings, and gotchas are preserved and indexed
• 🗂️ Stay organized without overhead — the framework does the filing, you do the thinking

📦 Installation

Homebrew (macOS / Linux)

brew install mnemcik/tap/cg

Upgrades follow the standard brew upgrade flow.

One-liner (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/mnemcik/consigliere/main/install.sh | bash

Downloads the latest release, verifies its SHA-256 against checksums.txt, and installs cg to ~/.local/bin. Pin a specific version with | bash -s -- --tag v1.2.3, install elsewhere with CG_INSTALL_DIR=/usr/local/bin, or see install.sh --help for all flags.

Manual download

Grab the archive for your platform from Releases and extract the cg binary anywhere on your $PATH. It's a single executable, no runtime needed — Windows builds ship as .zip, everything else as .tar.gz.

Windows

cg itself needs nothing else, but the hooks and status line it sets up for Claude Code are bash scripts. On Windows, Claude Code runs them in Git Bash, so install Git for Windows; without it, Claude Code runs them in PowerShell, where they don't run. cg init and cg sync warn when they can't find Git Bash. If it is installed somewhere cg and Claude Code don't look, set CLAUDE_CODE_GIT_BASH_PATH to its bash.exe in the env block of .claude/settings.json, which cg reads too, or as an environment variable (Claude Code on Windows).

Build from source

go install github.com/mnemcik/consigliere@latest

Claude Code slash commands

cg init installs /cg-init and /match-project into the workspace's .claude/commands/ directory. No separate plugin install step.

🚀 Quick Start

mkdir my-workspace && cd my-workspace
cg init
git init && git add -A && git commit -m "Initialize workspace"

That's it. You now have a complete workspace:

my-workspace/
├── 🔧 .cg.json              # Workspace identity
├── 📜 CLAUDE.md              # AI governance rules
├── 👤 PROFILE.md             # Your role and context
├── 🏛️ areas/                 # Domains of knowledge
├── 📁 projects/              # Active work
├── 💡 ideas/                 # Idea backlog
├── 📝 notes/                 # Findings & reference
├── 🔍 insights/              # Work style observations
└── 📋 templates/             # Templates for all items

Next steps:

1. ✏️ Edit PROFILE.md — tell your AI assistant who you are
2. 🏛️ Define your first area (a domain you're responsible for)
3. 💡 Create your first project or capture an idea

⚙️ How It Works

The workspace is your AI's memory

When you open Claude Code in a Consigliere workspace, it reads CLAUDE.md and immediately understands the workspace structure, conventions, and how to keep things organized. No setup, no prompting — it just works.

Everything flows through a lifecycle

  💡 Idea                              📁 Project
 ┌─────────────────────┐    ┌──────────────────────────────┐
 │ raw → exploring → ready ──→ defining → in-progress → done │
 └─────────────────────┘    └──────────┬───────────────────┘
                                       │
                            ┌──────────┴───────────┐
                            │  📝 Notes & Decisions  │
                            │  🏛️ Areas (ref hubs)   │
                            └──────────────────────┘

Ideas are lightweight captures. When they mature, they become projects with structured folders. Areas are the connective tissue — domains of knowledge that everything links to.

Your AI keeps things current

The CLAUDE.md rules instruct AI assistants to:

• ✅ Update project files after every session
• 🔄 Propagate information to related areas and projects
• 📝 Capture technical findings as searchable notes
• 🔍 Draft work style observations (you review before they become rules)

🛠️ CLI Commands

Command	Description
cg init	🏗️ Bootstrap a new workspace
cg init --force	🔄 Re-initialize (preserves CLAUDE.md and PROFILE.md)
cg match <prompt>	🔍 Find a project matching your description
cg status	📊 Workspace overview
cg migrate [--apply]	🗂️ Convert items from ## Meta blocks to YAML frontmatter; dry run unless --apply, and refreshes unedited item templates
cg version	ℹ️ Print installed version
cg update check	🔎 Check whether a newer cg release is available
cg update upgrade	⬆️ Download, verify, and install the latest release in place
cg share export <slug> --out <dir>	📤 Render a project into a read-only copy that can leave the workspace, after a confidentiality scan (docs)
cg share status [<audience>]	🔭 Compare each shared project with what its audience's share repo holds (docs)
cg share publish [<audience>]	🚀 Publish each audience's projects to its private share repo, with a terminal review for a first publish or added files (docs)

Examples

$ cg match "OAuth identity provider"
MATCH: OAuth & Identity Provider Strategy
SLUG: oauth-idp-strategy
PATH: projects/oauth-idp-strategy/
STATUS: In Progress

$ cg status
Consigliere workspace (v1.0.0)

Projects: 11 total, 9 active, 2 standing
Areas:    10
Ideas:    4
Notes:    12

🔄 Staying up to date

cg keeps itself current. Run cg update check any time, or cg update upgrade to install the latest release in place (the binary is downloaded from GitHub and SHA-256-verified before it replaces itself). Installs done via install.sh also auto-update in the background — a detached, debounced check that installs new minor/patch releases and prints ✅ cg updated to vX on your next run. Major (breaking) releases are never auto-installed; you get a heads-up and choose when.

Homebrew installs aren't self-replaced — cg points you at brew upgrade --cask cg.

Opt out with --no-auto-update (one run), CONSIGLIERE_AUTO_UPDATE=0 (disable the background check), or CONSIGLIERE_NO_UPDATE_NOTICE=1 (silence notices). Full design + state-file reference: docs/auto-update.md.

📚 Core Concepts

🏛️ Areas

Reference hubs — the single source of truth for a domain's systems, contacts, constraints, and current state. Think: "Identity & Auth", "API Management", "DevOps & Release". Every project, idea, and note links to an area instead of duplicating context.

📁 Projects

Each project is a folder with a standard structure:

File	Purpose
README.md	🎯 Current state, goals, scope — the source of truth
decisions.md	⚖️ Append-only log with status tracking
todo.md	✅ What's next
log.md	📓 What happened — session summaries, newest first

A project's README carries ## Goals when it terminates, or ## Standard to Maintain when it is a recurring duty with no finish line. Standing projects sit in their own ## Standing Commitments table in projects/TODO.md, are never offered as the next thing to work on, and cg status counts them apart from the active ones.

💡 Ideas

Lightweight captures: raw → exploring → ready → project (or parked / rejected). Low friction to capture, structured enough to act on.

📝 Notes

Session findings organized by category: tool gotchas, workflow patterns, architecture decisions, research, troubleshooting.

🔍 Insights

Draft observations about how you work with AI. Created automatically at session end, but never applied as rules until you explicitly promote them. You stay in control.

🔧 CLAUDE.md: Framework + Your Rules

The generated CLAUDE.md cleanly separates what Consigliere manages from what you customize:

<!-- cg:section:start=X -->     ← 🔒 Framework sections (updated by Consigliere)
<!-- user:section:start=X -->   ← ✏️ Your sections (never touched)

🏗️ Building from Source

git clone https://github.com/mnemcik/consigliere.git
cd consigliere
make build    # → ./cg binary
make test     # 🧪 Run tests
make lint     # 🔍 Run linters
make check    # ✅ Everything

See CONTRIBUTING.md for development details.

📊 Status

Beta — small user base. The CLI surface (init, match, status, version, update) is stable and covered by tests. Framework conventions (sentinel-delimited sections, .cg.json, template set) are in active evolution and may change between minor releases; migrations will be documented in CHANGELOG.md.

📖 Project docs

• Auto-update — cg update, the background worker, the major-version gate, and every state file
• Workspace sync — how cg sync reconciles a workspace's content with the framework
• Extensions (design) — the cg-extension.json manifest, registry, cg extension, and contribution points
• Authoring an extension — tutorial for writing a cg extension
• Contributing — setup, common tasks, release process, commit conventions
• Security policy — how to report vulnerabilities privately
• Code of conduct — Contributor Covenant 2.1
• Changelog — Keep a Changelog format, semver

📄 License

MIT