chore: restructure docs and add init.sh

Extract workflow, branching, PRs, and session rules from
AGENTS.md into docs/WORKFLOW.md. Move features.json and
claude-progress.txt format specs into dedicated reference
files. Slim AGENTS.md down to project overview and
knowledge base table.

Add init.sh to start and stop the dev environment with
port readiness checks. Update init-session command to
cover startup steps 1-6.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: twoGiants

.claude/commands/init-session.md

@@ -1,19 +1,28 @@
 ---
-allowed-tools: Bash(git log:*), Read
-description: Load recent context and wait for user direction
+allowed-tools: Bash(git log:*), Bash(pwd), Bash(./init.sh), Bash(yarn test*), Read
+description: Run startup sequence (steps 1-6 from docs/WORKFLOW.md)
 ---
 
 # Session Onboard
 
-Load recent context that isn't in AGENTS.md (which is always in context).
+Execute the startup sequence from `docs/WORKFLOW.md`. AGENTS.md is always in context — no need to read it explicitly.
 
 ## Steps
 
-1. **Read recent progress** — read `docs/claude-progress.txt` (only the last 3 days of entries matter).
+1. **Confirm working directory** — run `pwd`.
+
+2. **Orient** — read `docs/claude-progress.txt` (only the last 3 days of entries matter) and run:
 
-2. **Read recent commits** — run:
    ```bash
    git log --oneline --since="3 days ago"
    ```
 
-3. **Wait** — tell the user you're oriented and ask what they'd like to work on. Do NOT start any work autonomously.
+3. **Check struggles** — read `docs/agent-struggles.json`. If unresolved entries exist, present to user.
+
+4. **Pick feature** — read `docs/features.json`, find first `"passes": false` entry.
+
+5. **Start dev env** — run `./init.sh`.
+
+6. **Run tests** — run `yarn test` and verify app is healthy.
+
+7. **Wait** — tell the user you're oriented, report the picked feature, and ask what they'd like to work on. Do NOT start any work autonomously.

.gitignore

@@ -33,6 +33,7 @@ AGENTS.override.md
 
 # Local development configuration
 .dev
+.dev-logs
 
 # Yarn v4 (Berry)
 .yarn/*
@@ -42,3 +43,6 @@ install-state.gz
 !.yarn/releases
 !.yarn/sdks
 !.yarn/versions
+
+# MCP
+.playwright-mcp

AGENTS.md

@@ -11,100 +11,15 @@ See `docs/design/` for full design specs.
 
 | File | Purpose |
 |------|---------|
-| `docs/design/` | Design specs — "what to build" |
-| `docs/plans/active/` | Implementation plans in progress |
-| `docs/plans/completed/` | Finished plans |
-| `docs/references/` | LLM-friendly reference material |
+| `docs/WORKFLOW.md` | Startup sequence, feature dev sequence, branching, PRs, session rules |
 | `docs/ARCHITECTURE.md` | Layered architecture, dependency rules |
 | `docs/STYLEGUIDE.md` | Code style, naming conventions |
 | `docs/TESTING.md` | Testing strategy, tools, conventions, mock patterns |
-| `docs/features.json` | Inviolable feature list — ground truth |
-| `docs/claude-progress.txt` | Session handoff log |
+| `docs/design/` | Design specs — "what to build" |
+| `docs/plans/active/` | Implementation plans in progress |
+| `docs/plans/completed/` | Finished plans |
+| `docs/features.json` | Inviolable feature list — see [`references/features-json-readme.md`](docs/references/features-json-readme.md) |
+| `docs/claude-progress.txt` | Session handoff log — see [`references/claude-progress-readme.md`](docs/references/claude-progress-readme.md) |
+| `docs/agent-struggles.json` | Struggle log — see [`references/agent-struggles-readme.md`](docs/references/agent-struggles-readme.md) |
 | `docs/references/ocp-plugin-guide.md` | OCP dynamic plugin mechanics, i18n, extension points |
-| `docs/agent-struggles.json` | Struggle log — see `docs/references/agent-struggles-readme.md` |
-
-## Startup Sequence
-
-Every session, before doing any work:
-
-1. `pwd` — confirm working directory
-2. Read `docs/claude-progress.txt` + `git log --oneline -10` — orient
-3. Read `docs/agent-struggles.json` — if unresolved entries exist, present to user
-4. Read `docs/features.json` — pick first `"passes": false` entry
-5. Run `./init.sh` — start dev env
-6. Run tests — verify app is healthy
-7. If broken → fix first. If clean → start [Feature Development Sequence](#feature-development-sequence).
-
-## Branching
-
-Create a feature branch per plan: `<NNN>-<type>-<short-name>` where `<NNN>` matches the plan number and `<type>` the
-conventional commit type as per our [Git Commit Guide](/docs/references/commit-message-agent-readme.md#conventional-commits). Example: `001-feat-function-list-empty-state`.
-
-## Feature Development Sequence
-
-After [Startup Sequence](#startup-sequence), work through the picked feature:
-
-1. **Plan** — read `docs/ARCHITECTURE.md` + `docs/STYLEGUIDE.md` + `docs/TESTING.md`, then create implementation plan → `docs/plans/active/<incremented-number>-feature-<short-name>.md`
-2. **Branch** — create feature branch per [Branching](#branching) convention
-3. **Implement** — using `/executing-plans` skill
-4. **Review** — code review using `/requesting-code-review` skill, fix found issues
-5. **Manual Test** — use browser automation and validate it works in the browser
-6. **Complete** — flip `passes` to `true` in `docs/features.json`, update `docs/claude-progress.txt`, commit
-7. **PR** — push branch, open PR via `gh pr create` using `.github/pull_request_template.md`
-8. Move plan to `docs/plans/completed/`
-9. Stop, wait for user command
-
-## Session Rules
-
-- One feature at a time
-- Clean state at end (code suitable for merging to main)
-- Update `docs/claude-progress.txt` before session ends
-- Commit work to git before ending — follow `docs/references/commit-message-agent-readme.md` strictly
-
-## features.json
-
-Inviolable. The categories are `functional` or `technical`. You may only change the `passes` field to `true` — and only after:
-
-1. The corresponding e2e test passes
-2. You have validated the feature in a real browser via browser automation
-
-Never remove, reorder, or edit feature entries. Work on the first entry where `passes` is `false`.
-
-Format:
-
-```json
-{
-  "category": "functional",
-  "description": "...",
-  "steps": ["..."],
-  "passes": false
-}
-```
-
-## claude-progress.txt
-
-Append-only, newest-first. Add your entry at the top after the header. Format:
-
-```txt
----
-## YYYY-MM-DD | Session: <brief title>
-Worked on: <what you did>
-Completed:
-- <item>
-Left off: <what remains>
-Blockers: <any blockers or None>
-```
-
-## Continuous Improvement
-
-When you struggle, don't silently work around it. Log it to `docs/agent-struggles.json`:
-
-```json
-{
-  "date": "YYYY-MM-DD",
-  "description": "...",
-  "cause": "...",
-  "suggestion": "...",
-  "resolved": false
-}
-```
+| `docs/references/commit-message-agent-readme.md` | Git commit conventions |

docs/WORKFLOW.md

@@ -0,0 +1,50 @@
+# Workflow — func-console
+
+## Startup Sequence
+
+Every session, before doing any work:
+
+1. `pwd` — confirm working directory
+2. Read `docs/claude-progress.txt` + `git log --oneline -10` — orient
+3. Read `docs/agent-struggles.json` — if unresolved entries exist, present to user
+4. Read `docs/features.json` — pick first `"passes": false` entry
+5. Run `./init.sh` — start dev env
+6. Run tests — verify app is healthy
+7. If broken → fix first. If clean → start [Feature Development Sequence](#feature-development-sequence).
+
+## Feature Development Sequence
+
+After [Startup Sequence](#startup-sequence), work through the picked feature:
+
+1. **Plan** — read `docs/ARCHITECTURE.md` + `docs/STYLEGUIDE.md` + `docs/TESTING.md`, then create implementation plan → `docs/plans/active/<incremented-number>-feature-<short-name>.md`
+2. **Branch** — create feature branch per [Branching](#branching) convention
+3. **Implement** — using `/executing-plans` skill
+4. **Review** — code review using `/requesting-code-review` skill, fix found issues
+5. **Manual Test** — use browser automation and validate it works in the browser
+6. **Complete** — flip `passes` to `true` in [`docs/features.json`](references/features-json-readme.md), update [`docs/claude-progress.txt`](references/claude-progress-readme.md), commit
+7. **PR** — push branch, open PR per [Pull Requests](#pull-requests) convention
+8. Move plan to `docs/plans/completed/`
+9. Stop, wait for user command
+
+## Branching
+
+Create a feature branch per plan: `<NNN>-<type>-<short-name>` where `<NNN>` matches the plan number and `<type>` the conventional commit type as per our [Git Commit Guide](references/commit-message-agent-readme.md#conventional-commits). Example: `001-feat-function-list-empty-state`.
+
+## Pull Requests
+
+Open PRs via `gh pr create` using the template at `.github/pull_request_template.md`.
+
+**Title format:** `<Type>: <Sentence ending with a period.>` — capitalize the type and the first word, end with a period. Example: `Feat: Add function list page with empty state.`
+
+Types are the same as [conventional commits](references/commit-message-agent-readme.md#conventional-commits) but capitalized.
+
+## Session Rules
+
+- One feature at a time
+- Clean state at end (code suitable for merging to main)
+- Update [`docs/claude-progress.txt`](references/claude-progress-readme.md) before session ends
+- Commit work to git before ending — follow [`docs/references/commit-message-agent-readme.md`](references/commit-message-agent-readme.md) strictly
+
+## Continuous Improvement
+
+When you struggle, don't silently work around it. Log it to `docs/agent-struggles.json` — see [`docs/references/agent-struggles-readme.md`](references/agent-struggles-readme.md) for format.

docs/references/claude-progress-readme.md

@@ -0,0 +1,15 @@
+# claude-progress.txt
+
+Append-only, newest-first. Add your entry at the top after the header.
+
+## Format
+
+```txt
+---
+## YYYY-MM-DD | Session: <brief title>
+Worked on: <what you did>
+Completed:
+- <item>
+Left off: <what remains>
+Blockers: <any blockers or None>
+```

docs/references/features-json-readme.md

@@ -0,0 +1,19 @@
+# features.json
+
+Inviolable. The categories are `functional` or `technical`. You may only change the `passes` field to `true` — and only after:
+
+1. The corresponding e2e test passes
+2. You have validated the feature in a real browser via browser automation
+
+Never remove, reorder, or edit feature entries. Work on the first entry where `passes` is `false`.
+
+## Format
+
+```json
+{
+  "category": "functional",
+  "description": "...",
+  "steps": ["..."],
+  "passes": false
+}
+```

init.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+LOG_DIR=".dev-logs"
+CONSOLE_IMAGE="${CONSOLE_IMAGE:="quay.io/openshift/origin-console:latest"}"
+PLUGIN_PORT=9001
+CONSOLE_PORT=9000
+TIMEOUT=60
+
+wait_for_port() {
+  local port=$1
+  local label=$2
+  local elapsed=0
+
+  while ! bash -c "echo >/dev/tcp/localhost/$port" 2>/dev/null; do
+    if [ $elapsed -ge $TIMEOUT ]; then
+      echo "Error: $label did not start within ${TIMEOUT}s. Check $LOG_DIR/ for details."
+      exit 1
+    fi
+    echo "Waiting for $label (port $port)... ${elapsed}s"
+    sleep 1
+    elapsed=$((elapsed + 1))
+  done
+}
+
+stop_plugin() {
+  if pgrep -f "webpack serve" >/dev/null 2>&1; then
+    pkill -f "webpack serve" && echo "Stopped plugin dev server."
+  fi
+}
+
+stop_console() {
+  local container
+  container=$(podman ps -q --filter ancestor="$CONSOLE_IMAGE" 2>/dev/null || true)
+  if [ -n "$container" ]; then
+    podman stop "$container" >/dev/null && echo "Stopped OpenShift console."
+  fi
+}
+
+stop_dev() {
+  stop_plugin
+  stop_console
+}
+
+check_prerequisites() {
+  if ! command -v oc &>/dev/null; then
+    echo "Error: oc CLI not found. Install from https://console.redhat.com/openshift/downloads"
+    exit 1
+  fi
+
+  if ! oc whoami &>/dev/null; then
+    echo "Error: not logged in to OpenShift. Run 'oc login' first."
+    exit 1
+  fi
+}
+
+install_dependencies() {
+  if [ ! -d "node_modules" ]; then
+    echo "Installing dependencies..."
+    yarn install
+  fi
+}
+
+start_plugin() {
+  echo "Starting plugin dev server..."
+  yarn start >"$LOG_DIR/webpack.log" 2>&1 &
+}
+
+start_console() {
+  echo "Starting OpenShift console..."
+  yarn start-console >"$LOG_DIR/console.log" 2>&1 &
+}
+
+print_status() {
+  echo ""
+  echo "Dev environment started:"
+  echo "  Console: http://localhost:9000"
+  echo "  Logs:    $LOG_DIR/"
+  echo ""
+  echo "To stop: ./init.sh --stop"
+}
+
+main() {
+  mkdir -p "$LOG_DIR"
+  check_prerequisites
+  install_dependencies
+  stop_dev
+  start_plugin
+  wait_for_port "$PLUGIN_PORT" "Plugin dev server"
+  start_console
+  wait_for_port "$CONSOLE_PORT" "OpenShift console"
+  print_status
+}
+
+if [ "${1:-}" = "--stop" ]; then
+  stop_dev
+else
+  main
+fi