Agent skill

apex-docs

Stars 39

Forks 5

Install this agent skill to your Project

npx add-skill https://github.com/ariffazil/arifOS/tree/main/WORKSPACE/skills/apex-docs

SKILL.md

apex-docs — APEX Documentation Forge

Version: 2026.03.11-APEX Authority: arifOS F1-F13 Trigger: "forge docs", "apex docs", "document this", "harden documentation"

What This Skill Does

APEX-style documentation hardening using constitutional governance. Not generic "write good docs" — but forged documentation that reduces entropy, preserves reversibility, and links evidence.

The 6-Phase APEX Flow

READ → RISK → REASON → FORGE → VERIFY → SEAL

Phase 0: READ (Ground Truth)

bash

# Always start here
read <target_file>
git log --oneline <target_file> | head -5
ls -la <directory_context>

Output: Actual state. Not assumed. Not "probably".

Phase 1: RISK (CVSS for Docs)

Tier	Indicator	Action
Critical	Auth, payment, deletion logic undocumented	Immediate 888_HOLD
High	Public API mismatch with code	Same-day fix
Medium	Internal helper outdated	Backlog
Low	Typo, formatting	Batch
Cosmetic	"Sounds better" rewrites	Skip (PROPA)

Phase 2: REASON (F1-F4 Check)

F1 Reversibility:

Can this be undone in 60 seconds?
Git commit before edit

F2 Truth (τ ≥ 0.99):

Every claim links to source
Uncertainty stated explicitly (Ω₀)

F4 Clarity (ΔS ≤ 0):

Does this reduce confusion?
If file grows >20%, probably over-engineering

Phase 3: FORGE (Minimal Delta)

Rules:

Edit, don't rewrite
One purpose per commit
No PROPA (polished performance)
Raw > Perfect

Template for new sections:

markdown

## <Section Name>

> Source: `<file>:<line-range>`
> Last verified: `<YYYY-MM-DD>`
> Ω₀: <0.03-0.05> (uncertainty coefficient)

<Content>

<!-- If incomplete -->
**TODO:** <what's missing>

Phase 4: VERIFY

Check	Command
Links work	`grep -oP '(.*?)'
No orphans	`comm -23 <(grep '^## ' old.md) <(grep '^## ' new.md)`
Grammar	`aspell check <file>` (optional)
F4 Clarity	Read aloud: does it reduce confusion?

Phase 5: SEAL

bash

# Commit
git add <file>
git commit -m "<file>: <minimal description>

- Why: <F2 evidence>
- Risk: <CVSS tier>
- Reversible: <F1 check>"

# Log to memory
echo "- <file> hardened (<CVSS tier>)" >> memory/$(date +%Y-%m-%d).md

Constitutional Constraints

F1: Reversibility

All changes versioned
Can revert to pre-edit state
60-second recovery path

F2: Truth

Every claim → source link
τ (truth coefficient) ≥ 0.99
Unknown > Unsafe Certainty

F4: Clarity

ΔS ≤ 0 (entropy reduces)
Tables > Lists > Prose
No PROPA

F7: Humility

State Ω₀ (uncertainty)
Mark TODOs explicitly
"This section needs review"

F11: Command Auth

Destructive (delete, rewrite) → propose
Wait for F13 "do it"

F12: Injection Defense

Sanitize external inputs before including
No exec of extracted content

F13: Sovereignty

Human veto absolute
"Don't like it" = valid rejection

Drift Detection

Weekly scan:

bash

# Check for orphaned docs
for doc in *.md; do
  refs=$(grep -oP 'source:\s*\K[^\s]+' "$doc" | sort -u)
  for ref in $refs; do
    test -f "$ref" || echo "ORPHAN: $doc references missing $ref"
  done
done

Monthly audit:

Compare code exports to doc coverage
Flag undocumented public functions
Update last_verified dates

Example Workflow

User: "Harden AGENTS.md"

Agent:

READ → cat AGENTS.md, check git history
RISK → Public API access map → Critical tier
REASON → F1: reversible (git) ✓, F2: needs evidence links ✓, F4: ΔS? needs audit
FORGE → Add source links to §4, mark Ω₀ where uncertain
VERIFY → Links work, no orphans, clarity check
SEAL → Commit, log to memory/2026-03-11.md

Anti-Patterns (Never Do)

Anti-Pattern	Why	Alternative
"Documentation sprint"	Bulk rewrite = irreversible	One file at a time
"Polish pass"	PROPA — no substance	Skip if content correct
"Perfect grammar"	Cosmetic, not clarity	Raw transmission OK
"v2, v3, final"	File explosion	Edit in place
AI writes, human skips review	Hallucination risk	Human must verify F2

Quick Reference

bash

# Start any doc hardening
apex-docs harden <file>

# Check drift
apex-docs drift-scan <directory>

# Verify single file
apex-docs verify <file>

Ditempa bukan diberi

Maintainer

ariffazil Core maintainer

Source details

Full Name: ariffazil/arifOS
Branch: main
Path in repo: WORKSPACE/skills/apex-docs
License: GNU Affero General Public License v3.0
Topics: ai claude-code mcp mcp-client mcp-server ai-agents prompt-engineering llm model-context-protocol python agentic-ai multi-agent ai-safety fastmcp ai-governance agi constitutional-ai governance guardrails malaysia

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

ariffazil/arifOS

mcp-config-separation

39 5

Explore

ariffazil/arifOS

drift-watcher

Periodic knowledge freshness checker: detects when local configs, runbooks, or agent knowledge have drifted from the latest official docs. Reduces the stale-knowledge paradox over time. Use when: (1) periodic health checks or heartbeat runs, (2) before major operations, (3) user asks 'am I up to date', 'check for updates', 'is anything outdated', (4) after a software upgrade to verify configs still match new docs.

39 5

Explore

ariffazil/arifOS

MCP_CONFIG

39 5

Explore

ariffazil/arifOS

config-guardian

Universal governed config co-pilot. Before ANY change to ANY system: (1) check latest docs and running version (docs-first), (2) propose as diff with risk analysis, never apply directly (propose-only), (3) log every change with evidence and rollback (change ledger). Works for OpenClaw, Docker, PostgreSQL, Nginx, arifOS, or any software. Triggers on: 'change config', 'fix settings', 'update', 'propose patch', 'explain config', 'validate config', 'why did we change X'. Enforces propose-only workflow — human applies via git.

39 5

Explore

ariffazil/arifOS