What is ForgeOS?

If you're building with ChatGPT, Claude, Replit, Cursor, or similar tools, you can move fast — but things break down:

• Requirements are unclear or incomplete
• Outputs vary between runs
• Context gets lost between tools
• Features don't ship cleanly
• You spend more time fixing than building

ForgeOS adds just enough structure to fix this. It's not a tool. It's a loop.

The ForgeOS Loop

Every feature follows the same flow:

Getting Started

ForgeOS is not an app you install — it's a skeleton you use as the starting point for a new project. Clone it, make it yours, and start building.

Step 1 — Download ForgeOS

Clone the repo from GitHub — this becomes the starting point for your new project:

git clone https://github.com/lostinthewoods84/forgeOS.git my-project
cd my-project

Or open it on GitHub and use Code → Download ZIP, then rename the folder to your project name.

Step 2 — Make it your own

Remove the ForgeOS git history and start a fresh repo for your project:

rm -rf .git
git init
git add .
git commit -m "init: starting from ForgeOS"

Step 3 — Start your first Feature Card

Make a copy of the Feature Card template and name it after the feature you're building:

cp templates/FEATURE-CARD.md prompts/feature-[your-feature-name].md

Open that file. This is the document you'll fill in as you work through the loop.

Step 4 — Fill out READY (2 min)

This is the only section you write yourself, before touching any AI tool. If you can't fill it out clearly, you're not ready to build yet.

## 1. READY

What:
Add a notification button to the header

Why:
Users need visibility into updates and system activity

Success:
- Bell icon in header
- Shows unread count
- Opens dropdown panel

Not doing:
- No backend persistence
- No email notifications
- No settings/preferences

Step 5 — Generate a PRD with ChatGPT (5 min)

Paste your READY section into ChatGPT with this prompt:

I want to build this feature:

[paste your READY section]

Generate a short PRD with:
- Requirements
- Behavior description
- Edge cases
- Acceptance criteria

Keep it concise. One page max.

Paste the result into section 2 of your Feature Card. Then read it — cut anything the AI added that you didn't ask for.

Step 6 — Generate a Build Prompt with Claude (5 min)

Paste your PRD into Claude along with the Build Prompt template:

I need a build prompt for this feature.

Here's the PRD:
[paste PRD]

Create a build prompt using this template:
[paste contents of templates/build-prompts/TEMPLATE.md]

Paste the result into section 3 of your Feature Card. Review the file scope and constraints — make sure nothing outside your intended changes is included.

Step 7 — Implement (5–15 min)

Give the Build Prompt to your execution tool — Replit, Claude Code, Cursor, or manual coding. The tool should implement exactly what the prompt specifies and nothing more. If it starts inventing features, the Build Prompt needs to be tighter.

Step 8 — DONE check (2 min)

Compare the result against what you wrote in READY — not what the AI produced. Fill in section 4:

## 4. DONE CHECK

Did we achieve the outcome? yes

What actually changed for the user:
Bell icon appears in header, shows badge count, opens panel on click

What's still broken / missing:
No empty state yet

Good enough to ship? yes (POC)

Step 9 — Capture LEARNING (2 min)

After the feature ships, fill in section 5. This is the feedback loop that makes the next cycle better:

## 5. LEARNING

Expected:
Users will click the notification button to check updates

Observed:
Low engagement — few clicks in the first week

Delta:
Notifications may not be valuable enough yet

Decision:
Improve notification content before adding more features

As Complexity Grows

Add structure only when you feel friction, not in advance of it:

AI Roles

ForgeOS includes role definitions that constrain AI behavior at different stages. Include the relevant role file in your AI prompt:

Core Constraints

System Rules

• Do Not Overproduce — Only generate what can be reviewed. More artifacts = more waste.
• Limit Work in Progress — Prefer finishing over starting. WIP kills decision quality.
• AI Accelerates Execution, Not Authority — Every critical step requires human validation.
• Optimize for Learning, Not Output — Progress = validated assumptions + real-world feedback.

Operating Principles

• Pull, not push — Work is only created when the next stage is ready to receive it.
• Review is sacred — Protect time and space for thoughtful validation.
• Clarity over speed — Fast wrong decisions are more expensive than slow correct ones.
• Tight feedback loops — Every cycle should reduce uncertainty.

Anti-Patterns

• AI generating large volumes of unreviewed artifacts
• Multiple PRDs or features progressing without validation
• Skipping human review for the sake of speed
• Treating AI confidence as a substitute for human judgment
• Starting new features before capturing LEARNING from the last one

Architecture

Tool Stack

Key Artifacts

• Feature Card — The primary unit of work. Tracks a feature end-to-end.
• PRD — Product Requirements Document. Buildable spec generated from READY.
• Build Prompt — Scoped, constrained instruction for the execution tool.
• Role Files — AI persona definitions to constrain behavior per stage.