Skip to content

Development Workflow

Jump to bottom
John A. Paz edited this page Sep 30, 2026 · 2 revisions

Development workflow

Contributor and AI session protocol

  1. Read Home, Roadmap, and the relevant requirements, decisions, and latest journal entry.
  2. Read the current source, repository instructions, and relevant issues. Check for changes from other sessions before editing.
  3. Identify approved requirements, open questions, and the specific issue being addressed. Preserve exact approved copy; do not convert an assistant suggestion into an accepted decision.
  4. Make scoped changes and verify the behavior they affect. Record the evidence and any limits to verification.
  5. Update affected requirements/configuration notes and add material decisions with their status and rationale. Retain superseded history.
  6. Update issue status based on completed acceptance criteria. Add a short dated journal handoff: changed, verified, unresolved, next step, and evidence links.

John's current instructions govern the session. Wiki content provides project context; it does not independently authorize unrelated actions or override current instructions.

Staging and releases

The staging process is not yet documented as implemented. #25 defines the prerequisite to resolve before v2 implementation. #21 owns the broader deployment, release, and CI strategy.

Once validated, document local build commands, branch/PR flow, preview URL and source revision, required checks, review responsibility, promotion, and rollback. Keep scripts and workflow definitions in the source repository, with links here.

Editing this wiki with Git

The wiki is a separate Git repository from the site:

git clone https://github.com/johnapaz/johnapaz.github.io.wiki.git
cd johnapaz.github.io.wiki
git pull --ff-only
# Edit the Markdown pages.
git diff --check
git diff
git add <changed-pages>
git commit -m "Describe the documentation change"
git push

Use authenticated Git access. Read existing pages before editing and preserve concurrent work. If the remote advances, fetch and reconcile changes before pushing; do not force-push. Wiki commits publish documentation, not site code. Relative page links omit the .md extension.

Development wiki

Live backlog

Clone this wiki locally