safe-code

Spec-first repo hygiene. Project context, session memory, safe cleanup, and clean handoff in three commands.

---

Install

# Install into your current project
npx skills add afu-it/safe-code

# Install globally (all projects)
npx skills add afu-it/safe-code -g

# Preview before installing
npx skills add afu-it/safe-code --list

Works with Codex, Claude Code, Cursor, Windsurf, and 40+ other agents.

---

Three Commands

Command	What it does
/safe-code	Setup, auto-resume saved work, or run a fresh hygiene pass
/safe-code --continue	Explicitly resume saved work
/safe-code --save	Finalize context/docs, commit locally, and close session

If users forget --continue, /safe-code auto-detects saved unfinished state and resumes.

---

How It Works

/safe-code

 Step 0  →  Detect active agent and project root
 Step 1  →  Create/reconcile AGENTS.md, context/, and session docs
 Step 2  →  Load AGENTS.md first, then context files, then saved state if present
 Step 3  →  Check git rollback safety + graph readiness
 Step 4  →  Explore/audit repo facts before writing context
 Step 5  →  Draft or read active feature spec when building a feature
 Step 6  →  Execute scoped code changes, cleanup, or refactor only when in scope
 Step 7  →  Verify, review, debug failures if needed
 Step 8  →  Draft context/doc updates in SESSION.md
--save   →  Apply final context/docs + local commit only

Nothing is pushed. Nothing risky is deleted without rollback evidence.

---

Context + Session Docs

Every project gets one root entry point, project context, feature specs, and runtime session state:

your-project/
├── AGENTS.md
├── CHANGELOG.md
├── context/
│   ├── project-overview.md
│   ├── architecture.md
│   ├── user-preferences.md
│   ├── code-standards.md
│   ├── ai-workflow-rules.md
│   ├── ui-context.md
│   ├── progress-tracker.md
│   ├── current-issues.md        # local-only, gitignored, user-written
│   └── feature-specs/
│       └── 00-template.md
└── .codex/agents/               # or .claude/.cursor/.windsurf
    ├── ACTIVE.md
    ├── SESSION.md
    ├── LOG.md
    ├── BACKLOG.md
    ├── MEMORY.md
    └── safe-refactor-code.md

• AGENTS.md stays at root and tells agents what to read first.
• context/ is canonical long-term project brain.
• context/user-preferences.md stores explicit durable user preferences, like “SVG icons only, no emoji icons”.
• Agents watch for strong preference language like I don't want, aku taknak, I prefer, please remove, jangan, always, and never.
• context/feature-specs/ holds AI-written build specs, one unit per file.
• context/current-issues.md is manual user scratchpad, never committed.
• .codex/agents/ is runtime/session memory.

---

Draft Until Save

During work, safe-code drafts persistent documentation changes in SESSION.md.

/safe-code --save applies final updates to:

• context/*.md
• AGENTS.md
• ACTIVE.md
• LOG.md
• BACKLOG.md, MEMORY.md, safe-refactor-code.md when triggered
• CHANGELOG.md only for releasable changes

Exceptions written before save:

• missing scaffold files/folders
• /context/current-issues.md gitignore rule
• active feature specs in context/feature-specs/
• code changes required by user task

---

Existing Projects and Old Method Migration

safe-code works for blank, in-progress, finished, and old safe-code projects.

For existing projects:

• reads repo evidence first: README, manifests, routes, schemas, tests, configs
• backfills context files only from proven facts
• places unknown facts in context/progress-tracker.md Open Questions
• creates feature specs only for upcoming work, bugs, refactors, or missing documentation units

For old safe-code projects:

• keeps old continuity docs
• migrates useful facts into context/ as drafts
• treats context/ as canonical project context after /safe-code --save

---

Feature Specs

Feature specs are written by AI from user intent + context + repo evidence.

Example:

context/feature-specs/
├── 01-design-system.md
├── 02-editor.md
└── 03-auth.md

Each spec includes:

• goal
• scope and out-of-scope
• design/behavior
• likely touched files or areas
• dependencies
• verification checklist

safe-code should not implement feature work without an active spec unless the user asks for a tiny direct edit.

---

Current Issues

context/current-issues.md is created by safe-code, but manually written by the user.

It is gitignored:

/context/current-issues.md

User prompt inside the template:

Explore the current-issues.md file and deeply analyze the problem. Only when you have the analysis, give it back to me with the idea of how you're planning to solve it, and then wait for me to give you the green light to execute it.

Agents do not read this file unless explicitly asked.

---

Helper Skills

Users normally call only /safe-code.

Skill	Role	Called by safe-code?
senior-dev	Task lists, adversarial strategy, clean repo discipline	Yes
build-graph	Graph build/update when available	Yes
explore-codebase	Repo orientation and facts	Yes
codebase-pruner	Dead-code analysis and scoped cleanup	When in scope
safe-refactor-code	Refactor with impact checks	When in scope
review-changes	Delta review before final summary	After edits/risk
debug-issue	Failure/regression tracing	On failures/bugs

Helper skills analyze first and never make broad changes merely because /safe-code ran.

---

Execution Modes

Mode	When	What happens
A — Auto	Git clean, high-confidence, reversible	Runs scoped plan
B — Ask	Dirty worktree, borderline, broad scope	Shows plan, waits
C — Plan only	No rollback, orientation/audit, or requested	Findings only

---

What's New

v2.9 — six-file project context + feature specs.

• Added context/ project brain and context/feature-specs/ build specs.
• Added local-only context/current-issues.md template and gitignore rule.
• /safe-code auto-resumes saved sessions when users forget --continue.
• Persistent context/doc updates are drafted during work and finalized on /safe-code --save.
• Old safe-code continuity docs migrate into new context files safely.

v2.8 — explicit first-run, continue, and save commands.

v2.7 — code-review-graph and helper-skill orchestration.

---

New to skills?

Read the tutorial for step-by-step setup:

• English tutorial
• Tutorial Bahasa Melayu