Skip to content

README.md

Latest commit

 

History

History
158 lines (119 loc) · 8.82 KB

README.md

File metadata and controls

158 lines (119 loc) · 8.82 KB
Raw

Complex Project Discipline

A universal operational discipline for solo and small-team execution on complex multi-layer projects, packaged as a Claude Code skill.

Distilled from production-grade execution on a project that simultaneously ran a research line with measured gates, a production web service, a funding-readiness application cycle, and a layered AI-agent harness — and now stripped of all project-specific identifiers to be reusable across any complex project.

What this is

A working methodology for one person (or a very small team) to ship production-grade complex software with the integrity discipline of a much larger organization. It substitutes external structure (canonical state files, append-only logs, bounded execution flow, mechanical push gates) for the review redundancy a real team would provide.

The skill is designed to be loaded by Claude Code on narrow triggers — it does not auto-fire on every conversation. When triggered, it makes operational rules mechanical and explicit, so the agent and the human operator share the same discipline.

Who this is for

  • Solo founders running production software where one bad commit can cost a customer.
  • Independent researchers maintaining a public canonical record of measured gates and preserved failures.
  • Small engineering teams (2–4 people) wanting external structure to replace meeting-heavy coordination.
  • Funding applicants preparing alignment-funder cycles and needing reference qualification + disclosure discipline.
  • Multi-agent system engineers working with AI agents (Claude Code, Codex, etc.) and wanting layered harness — settings.json + hooks + sub-agents + skills — that mechanically enforces forbidden actions.

What's inside

SKILL.md                                          Entry + index. Read this first.

docs/                                             16 modular reference docs
  01_TRUTH_HIERARCHY_AND_STATE_FILES.md           Canonical state, 9-level hierarchy
  02_BOUNDED_EXECUTION.md                         Task pack format + 10-step flow
  03_VERIFICATION_DISCIPLINE.md                   "No artifact, no claim" + 6-condition gate
  04_BRANCH_AND_PUSH_DISCIPLINE.md                Main protection + explicit-unlock pattern
  05_APPEND_ONLY_LOGS.md                          Execution journal + weekly status
  06_CHANGE_CLASS_CLASSIFICATION.md               R0/R1/R2 + when-in-doubt rule
  07_UX_STANDARDS_CANONICAL.md                    10-standard distilled stack
  08_PRODUCTION_INFRA_DISCIPLINE.md               Deploy + DB volumes + tunnel
  09_CORPUS_DRIVEN_DEVELOPMENT.md                 7-step corpus pattern + thresholds
  10_FUNDING_READINESS_DISCIPLINE.md              Owner-operated + reference qualification
  11_COMMUNICATION_PATTERNS.md                    Apology + opt-in paths
  12_CLAUDE_CODE_HARNESS_PATTERN.md               8-step layered harness rollout
  13_MEMORY_STRUCTURE.md                          Repository + state + top-of-stack
  14_SESSION_CLOSE_DISCIPLINE.md                  Close gate + final answer gate
  15_ANTI_PATTERNS.md                             41 catalogued anti-patterns + counter-patterns
  16_POLISH_DISCIPLINE.md                         Adversarial re-read

templates/                                        8 reusable forms
  task_pack.md                                    9-section task pack
  bounded_packet.json                             Bounded execution packet schema
  agents_log_row.md                               Pipe-separated execution log row
  weekly_status_section.md                        Per-task ## section
  reference_prep_brief.md                         Integrity-aligned ground-truth context
  apology_email_pattern.md                        Customer-relationship debt closure
  paste_ready_field_map.md                        Form-submission paste-ready map
  claude_settings.json                            Claude Code settings.json template

checklists/                                       6 actionable gates
  pre_commit_check.md                             Before any git commit
  pre_push_check.md                               Before any git push
  session_close_check.md                          End-of-session full closure
  final_answer_gate.md                            6-condition gate before "done"
  ux_per_surface_check.md                         Per-public-surface UX checklist
  deploy_verification_check.md                    9-phase production deploy verification

Total: 28 files, ~5,300 lines.

How to use

As a Claude Code skill

  1. Place this directory under your Claude Code skills path (typically ~/.claude/skills/ or your project's .claude/skills/).

  2. The skill auto-loads on narrow triggers (see SKILL.md frontmatter description):

    • "set up project discipline"
    • "task pack"
    • "bounded execution"
    • "funding readiness"
    • "UX standards canonical"
    • "Claude Code harness"
    • "session continuity"
    • "memory structure"
    • "verification gate"
    • "append-only logs"
    • "owner-operated disclosure"
    • "reference prep"
    • "preserved failure"
    • "MERGE_MAIN_NOW"

  3. Once loaded, the agent reads SKILL.md and follows progressive disclosure into the relevant docs/ modules.

As reference documentation

Read directly. The seven core principles in SKILL.md cover the key ideas; docs/ provides depth.

Recommended reading order for first pass:

  1. SKILL.md
  2. docs/01_TRUTH_HIERARCHY_AND_STATE_FILES.md
  3. docs/02_BOUNDED_EXECUTION.md
  4. docs/05_APPEND_ONLY_LOGS.md
  5. docs/15_ANTI_PATTERNS.md (catalogue of what NOT to do)

Then domain-specific modules as needed.

As a fork starting point

Fork this skill into a project-specific copy. Adapt:

  • Funder names to your target ecosystem
  • Hostnames and IP addresses to your infra
  • Branch naming conventions to your project (test, dev, etc.)
  • Specific stack choices (Docker / Kubernetes, PostgreSQL / other DB, etc.)
  • Multi-language requirements (or remove i18n sections if monolingual)

Date your fork. Document divergences. Do not modify the canonical version.

The seven core principles

  1. Truth hierarchy is non-negotiable. Single canonical live-state file. Lower levels never override higher.
  2. Bounded execution beats heroic execution. One task = one reason. One commit = one logical change.
  3. No artifact, no claim. PARTIAL is honest. UNVERIFIED is required.
  4. Append-only logs are the spine. Old entries never edited. New entries always appended.
  5. Disclosure-first integrity beats hidden conflicts. Owner-operated systems explicitly named.
  6. Preserved failures are a competitive advantage. Document FAIL canonically, do not silently rewrite.
  7. Main branch is sacred until explicit unlock. Mechanically enforced via permissions.deny.

Provenance

Distilled from a 2026 solo-founder project running:

  • A research line with 34 measured gates (32 PASS / 2 preserved FAIL)
  • A production web service with single-node Docker Compose + Cloudflare Tunnel ingress
  • A funding-readiness cycle across multiple alignment-funder targets
  • A layered Claude Code harness (settings.json + SessionStart hook + corpus runner + sub-agent + project skill)

All identifying information about the source project (organization names, partner relationships, specific scientific gates, personal contact info, server addresses, repository identifiers) has been stripped from this canonical version. The patterns remain; the specifics do not.

License

This work is released under MIT License — free to use, modify, and redistribute with attribution.

Contributing

This is a snapshot of working discipline patterns. Fork freely. Send PRs for:

  • Universal-pattern improvements distilled from your own project experience.
  • New anti-patterns observed in real solo-founder execution (see docs/15_ANTI_PATTERNS.md format).
  • New funder profiles in docs/10_FUNDING_READINESS_DISCIPLINE.md (alignment-funder ecosystem evolves; keep the per-funder notes current).

Do NOT send PRs that:

  • Add project-specific identifiers (the canonical version is intentionally generic).
  • Introduce dependencies on specific tooling beyond Claude Code, git, Docker.
  • Soften the integrity discipline (preserved failures, append-only logs, disclosure-first rules are load-bearing).

Related work

This skill complements but does not replace:

  • Anthropic Claude Code documentation
  • Boris Cherny's published guidance on Claude Code skills, hooks, and sub-agents
  • WCAG, ISO 9241-110, Nielsen heuristics, OWASP Top-10, GDPR, Lighthouse — referenced in docs/07_UX_STANDARDS_CANONICAL.md

One-line summary

External structure for solo-founder execution: truth hierarchy, bounded execution, append-only logs, verification discipline, disclosure-first integrity, preserved failures, mechanical main-branch protection. Make the agent and the operator share the same rules.