Skip to content

Add Why, Architecture, and Configuration sections to README #20

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AnExiledDev merged 1 commit into from
Feb 26, 2026
Merged

Add Why, Architecture, and Configuration sections to README #20

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .devcontainer/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@

### Added

#### README
- **"Why CodeForge?" section** — motivation and value proposition explaining the project's origins as a power user's personal setup
- **Architecture overview** — three-layer diagram (DevContainer → CodeForge Layer → Claude Code) with brief descriptions and link to full architecture docs
- **Configuration summary** — table of key config files with links to the documentation site

#### Public Repo Quality
- **CI workflow** (`.github/workflows/ci.yml`) — test and lint jobs on PRs and pushes to main (Node 18, `npm test` + Biome check)
- **CodeQL security analysis** (`.github/workflows/codeql.yml`) — JavaScript scanning on PRs, pushes, and weekly schedule
Expand Down
49 changes: 49 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@

A curated development environment optimized for AI-powered coding with Claude Code. CodeForge comes pre-configured with language servers, code intelligence tools, and official Anthropic plugins to streamline your development workflow.

## Why CodeForge?

Claude Code is powerful out of the box, but getting the most from it takes significant configuration — custom agents, safety plugins, code quality hooks, system prompts, and development tools that aren't obvious from the docs. CodeForge is a Claude Code power user's personal development environment, packaged so anyone can use it.

Instead of spending hours discovering and configuring advanced features like built-in agent replacement, automated code quality pipelines, or spec-driven workflows, you get a production-tested setup in one command. It's opinionated by design — every default reflects real daily use, not theoretical best practices.

## Installation

Add CodeForge to any project:
Expand Down Expand Up @@ -75,6 +81,49 @@ tmux, agent-browser, claude-monitor, ccusage, ccburn, ccstatusline, ast-grep, tr

The `agent-system` plugin includes 17 specialized agents (architect, explorer, test-writer, security-auditor, etc.). The `skill-engine` plugin provides 22 general coding skills, `spec-workflow` adds 8 spec lifecycle skills, and `ticket-workflow` provides 4 ticket management skills.

## Architecture

CodeForge operates in three layers, each building on the one below:

```
┌──────────────────────────────────────────────┐
│ Claude Code │
│ AI assistant, tool execution, Agent Teams │
├──────────────────────────────────────────────┤
│ CodeForge Layer │
│ Plugins · Agents · Skills · Hooks · Rules │
├──────────────────────────────────────────────┤
│ DevContainer │
│ Runtimes · CLI Tools · LSP Servers │
└──────────────────────────────────────────────┘
```
Comment on lines +88 to +99
Copy link

@coderabbitai coderabbitai bot Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add a language hint to the architecture code fence (MD040).

Markdown lint is correct here: the fenced block should declare a language for consistency/tooling compatibility.

Suggested patch 
-```
+```text
 ┌──────────────────────────────────────────────┐
 │                 Claude Code                   │
 │   AI assistant, tool execution, Agent Teams   │
@@
 └──────────────────────────────────────────────┘
</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 87-87: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 87 - 98, The fenced ASCII-art block in README.md
lacks a language hint causing MD040; update the triple-backtick fence for the
block that contains the Claude Code/CodeForge/DevContainer diagram to include a
language identifier (for example "text") so the fence becomes ```text,
preserving the existing ASCII content inside; locate the README.md fenced block
that starts with the box drawing and add the language hint to the opening fence.


**DevContainer** — The foundation. A Python 3.14 container with Node.js, Rust, and Bun runtimes, plus 22 custom features that install development tools (ast-grep, tree-sitter, biome, ruff, and others).

**CodeForge Layer** — The intelligence. 13 plugins register hooks that validate commands, inject context, and enforce safety. 17 agents provide specialized personas. 35 skills offer on-demand reference material. System prompts and rules shape behavior.

Comment on lines +101 to +104
Copy link

@coderabbitai coderabbitai bot Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Feature count is inconsistent in this section.

Line 100 says “22 custom features”, but the README’s own “Custom Features (21)” section lists 21. Please align this count to avoid reader confusion.

Suggested patch 
-**DevContainer** — The foundation. A Python 3.14 container with Node.js, Rust, and Bun runtimes, plus 22 custom features that install development tools (ast-grep, tree-sitter, biome, ruff, and others).
+**DevContainer** — The foundation. A Python 3.14 container with Node.js, Rust, and Bun runtimes, plus 21 custom features that install development tools (ast-grep, tree-sitter, biome, ruff, and others).
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**DevContainer** — The foundation. A Python 3.14 container with Node.js, Rust, and Bun runtimes, plus 22 custom features that install development tools (ast-grep, tree-sitter, biome, ruff, and others).
**CodeForge Layer** — The intelligence. 13 plugins register hooks that validate commands, inject context, and enforce safety. 17 agents provide specialized personas. 35 skills offer on-demand reference material. System prompts and rules shape behavior.
**DevContainer** — The foundation. A Python 3.14 container with Node.js, Rust, and Bun runtimes, plus 21 custom features that install development tools (ast-grep, tree-sitter, biome, ruff, and others).
**CodeForge Layer** — The intelligence. 13 plugins register hooks that validate commands, inject context, and enforce safety. 17 agents provide specialized personas. 35 skills offer on-demand reference material. System prompts and rules shape behavior.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 100 - 103, Update the DevContainer feature count to
match the documented list by changing the phrase "22 custom features" in the
"DevContainer" paragraph to "21 custom features"; verify the "Custom Features
(21)" section header and any other occurrences of the custom features count
(search for "22 custom features" and "Custom Features (21)") so all counts are
consistent across the README.

**Claude Code** — The AI assistant, executing tools and coordinating work. CodeForge enhances it through configuration — replacing built-in subagents, adding safety guardrails, and wiring up quality checks that run automatically.

For the full architecture breakdown — hook pipeline, agent routing, skill loading, and design principles — see the [Architecture Reference](https://anexileddev.github.io/CodeForge/reference/architecture/).

## Configuration

All configuration lives in `.devcontainer/` and deploys automatically on container start. Key files:

| File | What It Configures | User-Modifiable? |
|------|--------------------|------------------|
| `config/defaults/settings.json` | Model, plugins, permissions, environment variables | Yes |
| `config/defaults/main-system-prompt.md` | Claude's behavioral guidelines and directives | Yes |
| `config/defaults/keybindings.json` | Keyboard shortcuts | Yes |
| `config/defaults/ccstatusline-settings.json` | Terminal status bar widgets and layout | Yes |
| `config/file-manifest.json` | Which config files deploy and how they update | Yes |
| `devcontainer.json` | Container image, features, runtimes, ports | Yes |
| `.env` | Setup phase toggles (auth, plugins, aliases, etc.) | Yes |

Config files use SHA-256 change detection — your edits persist across container rebuilds unless the source changes. Set a file's overwrite mode to `"never"` in `file-manifest.json` to permanently preserve your customizations.

For the complete configuration guide, see the [documentation site](https://anexileddev.github.io/CodeForge/customization/configuration/).

## Quick Start

1. **Install**: `npx codeforge-dev`
Expand Down
Loading