Skip to content

examples.md

Latest commit

 

History

History
148 lines (109 loc) · 5.87 KB

examples.md

File metadata and controls

148 lines (109 loc) · 5.87 KB
Raw

Examples

Chinese version: examples.zh-CN.md

The Forma repository includes two kinds of real examples:

Together, they show how durable project standards become an Installed workflow and how that workflow governs a concrete task.

How To Read The Examples

Material What it shows
Profile sample Evidence priorities, engineering boundaries, validation, proof, stop conditions, tools, and source adapters that should apply repeatedly.
Generated output Skill names, stage-owned references and scripts, target metadata, and provenance compiled from a Profile.
Plan files and runs How one task records its accepted plan, work units, validation, code snapshot, and delivery evidence.

Sample Software Profile

Start with:

examples/profiles/sample-software/sample-software-plan-first.yaml

This sanitized Profile shows a general software workflow that:

  • keeps early planning in conversation while goal, scope, approach, validation, impact, and source-of-truth needs are settled;
  • gathers project rules, target code, validation commands, and protected or generated paths through read-only grounding;
  • writes plan.md and tasks.md after the decisions and evidence are ready;
  • executes one accepted task at a time and stops when an assumption, source of truth, or validation model changes;
  • continues through remaining tasks while planning, evidence, validation, and worktree-safety gates remain clear.

Its stage-owned references include:

  • software-control-model.md
  • software-impact-profiles.md
  • software-artifact-evidence-boundary.md
  • software-feedback-and-proof.md
  • software-review-checks.md

The Profile demonstrates how a project can define what makes planning, implementation, evidence, and delivery acceptable without repeating those standards in every task request.

Sample Backend Profile

Start with:

examples/profiles/sample-backend/sample-backend-go-github-issue-tracked.yaml

This Profile composes general backend standards, a development overlay, a Go language overlay, and a GitHub issue source adapter. It covers:

  • behavioral scope and root-cause implementation;
  • backward compatibility and sensitive-data handling;
  • public API, stream, service, persistence, and data-flow impact;
  • the source contract needed before a public API or stream change is locked;
  • implementation stop conditions when contract-visible impact expands;
  • Go formatting, module-local tests, and behavior-test expectations;
  • GitHub issue context for the workflow skills that plan and lock work.

The example shows how one backend workflow can place API impact, source adapters, language validation, and stop conditions in the exact skills where they act.

Sample Multi-project Profile Family

Start with:

examples/profiles/sample-family/

This fixture models two repositories plus a sanitized user home. It shows the family layout under user-home/.forma/profiles/sample-family/, independently named shared and project layers, copied shared/project resources, and both .forma/profile.yaml and .forma/profile-ref.yaml in each repository.

The local and reference entrypoints generate the same effective workflow; only their truthful Profile provenance differs. In real use, user-home represents ~, and the Agent creates this shape only after previewing the complete write set and receiving approval. It preserves the local files, so a later build can choose either entrypoint.

Inspect Generated Output

Build and verify a sample locally:

forma build bundle --target codex \
  --profile examples/profiles/sample-backend/sample-backend-go-github-issue-tracked.yaml \
  --output /tmp/forma-sample-backend-codex

forma verify /tmp/forma-sample-backend-codex

The generated bundle contains:

  • backend-plan-first-* skill directories selected by the Profile;
  • the GitHub issue helper in the skills that use it;
  • references copied into their owning skills;
  • .forma-manifest.json with the target, emitted skill names, resolved Profile order, and source hashes.

Real Forma Plan Files And Runs

Forma tracks its own development under plans/issue-*/. Start with:

Run What it shows
issue-project-rule-workflow-quality Shared engineering-quality standards, scored delivery evaluation, Agent diagnosis, public documentation, and regenerated release artifacts.
issue-codex-plugin-profile-naming Codex plugin identity, skill-name propagation, verifier failure cases, and install boundaries.
issue-bundle-plugin-install-surface Bundle and plugin generation, install surfaces, committed release artifacts, and documentation.

Each issue records:

  • plan.md: goal, scope, approach, constraints, acceptance, and validation;
  • tasks.md: accepted tasks, dependencies, task validation, and evidence responsibilities;
  • runs/task-*.md: changed files, validation results, snapshots, and risk notes.

For example, issue-project-rule-workflow-quality/plan.md requires one engineering-quality model across planning, implementation, review-ready evidence, delivery evaluation, and rework. Its matching run files show the commands, snapshots, and generated artifacts used to prove delivery.

Related Docs