Skip to content

develop.md

Latest commit

 

History

History
109 lines (73 loc) · 6.45 KB

develop.md

File metadata and controls

109 lines (73 loc) · 6.45 KB

Development & Contribution

The OpenCode Framework enforces a high-discipline development lifecycle. Whether you are a human or an AI contributor, adherence to these standards is mandatory.

🔄 The Mandatory Workflow Lifecycle

Every non-trivial change must follow this strict three-phase process:

[Phase 1: Discovery] -> [Phase 2: Strategy] -> [Phase 3: Execution]
(Audit/Research)        (Planning Bridge)      (Tasks/Drafting)

1. Discovery & Audit (Read-Only)

Before proposing a change, you must gather context and identify risks. Use the specialized discovery commands:

  • /research: For domain knowledge and external libraries.
  • /audit: To audit the codebase for technical debt and architecture issues.
  • /debug: To perform a root-cause analysis (RCA) on a bug.

Crucially, these commands are read-only; they produce artifacts (.knowledge/notes/, *.review.md), not code changes.

2. Strategic Planning (The Bridge)

A feature or fix is not considered "active" until a persistent Markdown plan has been created in the .knowledge/plans/ directory. Use the /plan command to synthesize the artifacts generated in Phase 1 into an actionable strategy.

3. Execution & Validation (Side-Effects)

Once a plan is approved, you move to execution. This is the only phase where files are modified.

For Code: The TCR Protocol

The /task command is the primary tool for repository execution:

  • task add: Adds a new task using the task tool.
  • task start --task-id X: Marks a task as in-progress.
  • task list: Provides a summary of the roadmap and current priorities.
  • task archive --task-id X: Marks a task as done.

CLI-First Roadmap Discipline: The project roadmap (tasks.yaml) must never be edited by hand. All task operations must be performed via the task tool or the corresponding /task actions. This ensures structural integrity and a verifiable audit trail.

The TCR Loop (Work Action)

  1. Phase 1 (Pre-flight Verification): The agent verifies that the working tree is clean, the current branch is main, and make test passes as a baseline.
  2. Phase 2 (Task Isolation): A dedicated feature branch (e.g., feature/task-name) is auto-generated and checked out. All work occurs on this isolated branch.
  3. Phase 3 (The Red-Green-Verify Loop): For every granular step of the implementation:
    • Red: Write a failing test and verify failure with make test.
    • Green: Implement the minimal code to pass the test.
    • Verify: Run make test.
      • Pass: git commit the step.
      • Fail: Attempt one quick fix. If it fails again, the change is automatically reverted (git checkout .).
  4. Phase 4 (Integration): Once all steps are complete, the agent performs a final test run. Upon approval, the branch is merged into main and deleted.

4. Forensic Investigation (The Scientific Debugging Discipline)

When a bug is detected, the /debug command enforces a structured, scientific investigation:

  1. Phase 1 (Status & Context): Analyze the current environment and gather reproduction information.
  2. Phase 2 (Hypothesis Formulation): Formulate a specific hypothesis for the root cause.
  3. Phase 3 (Isolated Testing): Test the hypothesis on a temporary diagnostic branch (debug/hyp-*). Diagnostic code should be minimal and focused.
  4. Phase 4 (Synthesis & RCA): Summarize the investigation into a Root Cause Analysis (RCA) report. This report serves as the documentation for the subsequent fix.

5. Audit & Documentation (NEW)

Before merging or committing any final change, the work must be documented in the daily journal. This is enforced by a timestamp-based git hook. Use the following tool to satisfy the requirement:

journal add "one-line description of the work"

Failure to do this will block your commit or turn execution.

✅ Testing & Quality Standards

  • Automated Context Minification: To ensure maximum token efficiency and prevent context saturation during long sessions, the framework automatically identifies and replaces redundant <instruction> blocks from previous turns with a placeholder. Only the latest instruction is passed to the model in its full form, ensuring the agent stays focused on the current task while maintaining structural operational context.
  • Agent-Driven Validation: This project maintains a minimalist, transient testing philosophy. Instead of a static suite of thousands of unit tests, it relies on high-discipline agent execution and Grounded Experimentation to verify behavior in real-time.
  • On-the-Fly Verification: During the mandatory TCR (Test-Commit-Revert) loop, the agent is required to write specific, temporary test cases (e.g., test_feature_x.py) that verify the granular step being implemented.
  • Source of Truth: The makefile is the central definition of project health. Even if it initially points to an empty test target, it serves as the hook point for the agent's automated validation.
  • The TCR Mandate: The primary mechanism for ensuring "Green-only" development is the mandatory Test-Commit-Revert loop. If a change fails its temporary verification, it is instantly reverted, ensuring the main branch remains a "known-good" state.

🌲 Git & Source Control

1. Clean Working Tree

The framework requires a clean working tree for critical actions. Commit often to avoid merge conflicts or large, unmanageable diffs.

2. Conventional Commits

All commit messages must follow the Conventional Commits standard:

  • feat:: A new feature for the user (e.g., feat(hooks): add notify-send alert).
  • fix:: A bug fix for the user.
  • docs:: Documentation-only changes.
  • chore:: Maintenance, dependencies, or internal tooling updates (e.g., chore(release): version 0.17.1).
  • refactor:: Code changes that neither fix a bug nor add a feature.

3. Commit Scoping

When possible, provide a scope to the commit message (e.g., feat(onboard): add documentation discovery).

✍️ Documentation Style

  • Markdown: All documentation and logs must be in GitHub-flavored Markdown.
  • Kebab-case: Use kebab-case for all filenames in the docs/, .knowledge/plans/, and .knowledge/notes/ directories.
  • Direct & Technical: Documentation should be concise, high-signal, and technically rigorous.

Return to the Project Overview.