Vibe Code Common Sense

My biggest lesson from Agentic Coding (read vibe coding) is :

Treat every AI agent as dumb until the project proves otherwise.

Agents can move fast, but at the start of a project you are vulnerable.

The idea is still loose, the architecture is undecided, the roadmap is unclear, and the
agent will happily generate confident slop if you do not give it rails.

Vibe Code Common Sense is a reusable coding agent skill (Codex skill/ Claude Code Plugin) for guiding AI-built projects
responsibly.

It helps turn a raw idea into a professional, trackable project with a blueprint, roadmap, PR workflow, agent instructions, and a living
progress tracker.

What It Creates

• README.md
• AGENTS.md
• docs/PROJECT_BLUEPRINT.md
• docs/PRODUCT_TIMELINE.md
• docs/ROADMAP.md
• docs/ARCHITECTURE.md
• docs/DEVELOPMENT_CYCLE.md
• decision records

Core Rule

Every PR updates docs/PRODUCT_TIMELINE.md.

That file is the project tracker. Completed work is marked [x] with the PR
number, and the next unchecked item tells the agent what to build next.

How To Use It

Use Vibe Code Common Sense before the agent writes product code.

The first run should create rails:

• project explanation;
• agent instructions;
• roadmap;
• architecture notes;
• development workflow;
• PR-sized progress tracker.

After that, every build should come from the first unchecked item in
docs/PRODUCT_TIMELINE.md.

Codex Install

In Codex, ask:

Install the skill from GitHub:
https://github.com/Njengah/vibe-code-common-sense

Then open a new project folder and say:

Use $vibe-code-common-sense.

I have a new project idea. Do not build product features yet.
First create the professional project rails and progress tracker.

My idea is:
[paste your idea here]

Claude Code Install

This repo is also packaged as a Claude Code plugin with
.claude-plugin/plugin.json.

In Claude Code, add the marketplace:

/plugin marketplace add Njengah/vibe-code-common-sense

Then install the plugin:

/plugin install vc-sense@vibe-code-common-sense

Reload plugins so the new skill is available in the current session:

/reload-plugins

Then run it in a new project:

/vc-sense:vc-sense

I have a new project idea. Do not build product features yet.
First create the professional project rails and progress tracker.

My idea is:
[paste your idea here]

If your Claude Code setup uses local plugin directories instead, clone this repo
and run Claude Code with the plugin directory:

git clone https://github.com/Njengah/vibe-code-common-sense.git
claude --plugin-dir ./vibe-code-common-sense

Any Agent

If your agent does not support skills or plugins, paste this instruction:

Read and follow this project setup system:
https://github.com/Njengah/vibe-code-common-sense/blob/main/SKILL.md

Do not build product features yet. First create the project rails:
README.md, AGENTS.md, docs/PROJECT_BLUEPRINT.md, docs/PRODUCT_TIMELINE.md,
docs/ROADMAP.md, docs/ARCHITECTURE.md, docs/DEVELOPMENT_CYCLE.md, and
docs/DECISIONS.md.

What Good Output Looks Like

After the first run, the project should have:

README.md
AGENTS.md
docs/PROJECT_BLUEPRINT.md
docs/PRODUCT_TIMELINE.md
docs/ROADMAP.md
docs/ARCHITECTURE.md
docs/DEVELOPMENT_CYCLE.md
docs/DECISIONS.md

The most important file is docs/PRODUCT_TIMELINE.md.

Every future PR should:

1. read docs/PRODUCT_TIMELINE.md;
2. build the first unchecked item;
3. open a focused PR;
4. mark that item [x] with the PR number;
5. show the next unchecked item.

Compatibility

• Codex reads SKILL.md, references/, and optional agents/openai.yaml.
• Claude Code reads the plugin manifest in .claude-plugin/plugin.json, plus
  the short /vc-sense:vc-sense skill command.
• Other agents can use the system manually by reading SKILL.md.

The Claude plugin wrapper uses disable-model-invocation: true, so Claude Code
users invoke it explicitly. The shared root SKILL.md stays Codex-compatible and
does not include Claude-only frontmatter.

Documentation

Docs: https://njengah.github.io/vibe-code-common-sense/