# Flowtend Skill Authoring If you are an agent reading this page, create or update the Flowtend skill for the runtime you are using. Codex and Claude Code use different local skill roots, but the Flowtend contract is the same: REST-first, project-scoped, and explicit about auth. ## Guide Map | Label | Value | Notes | | --- | --- | --- | | Default behavior | `Runtime-native flowtend-api skill` | First detect whether the user is running Codex or Claude Code, then create or update the matching skill path. | | Codex result | `~/.codex/skills/flowtend-api/SKILL.md` | Use this path when the current agent runtime is Codex. | | Claude result | `~/.claude/skills/flowtend-api/SKILL.md` | Use this path when the current agent runtime is Claude Code. | | CLI only if explicit | `~/.codex/skills/flowtend-cli/SKILL.md or ~/.claude/skills/flowtend-cli/SKILL.md` | Use flowtend-cli only for repo-local CLI or OSS-compatible requests, again under the current runtime's skill root. | | Legacy plugin | `~/.claude/plugins/flowtend/` | A pre-existing Claude plugin mirror may be read as fallback compatibility, but it is not the primary Claude skill path. | | Contract | `/v1/projects/{project_id}/...` | Use project-scoped Flowtend routes only. Do not use legacy global routes. | | Reusable auth | `~/.codex/.flowtend/project-.env or ~/.claude/.flowtend/project-.env` | Store FLOWTEND_API_* env vars under the current runtime's Flowtend env path and keep secrets out of SKILL.md. | ## Agent Instructions - Detect the current agent runtime before writing files: Codex uses ~/.codex/skills, Claude Code uses ~/.claude/skills. - Default to flowtend-api and write ~/.codex/skills/flowtend-api/SKILL.md for Codex or ~/.claude/skills/flowtend-api/SKILL.md for Claude Code. - Keep the installed flowtend-api skill as a small bootstrap: load the raw Markdown skill-authoring contract before route, workflow, or evidence decisions. - If live Flowtend credentials are missing, ask the user for the token value before you finish. - When the user wants reusable setup, store the current FLOWTEND_API_* env vars in the runtime-native env file: ~/.codex/.flowtend/project-.env for Codex or ~/.claude/.flowtend/project-.env for Claude Code. - Switch to flowtend-cli only when the user explicitly asked for CLI-only or OSS-compatible behavior. - Treat the public Flowtend docs as the source of truth; use the SKILL.md fallback only when those docs cannot be reached. - Start every task scan with GET /workflow/summary or GET /tasks?view=agent before pulling full task bodies; fetch GET /tasks/{task_id} and /artifacts only after the actionable set is narrowed. - If the prompt defines repo-work completion, tie it to the project's review setting instead of inventing a generic reviewed state. - If the user asks to clear backlog until no tasks remain, keep looping on refreshed actionable tasks and do not stop just because the backlog count changed or grew. - Never write secrets into SKILL.md or normal output. - Do not create README.md, CHANGELOG.md, setup notes, or helper files unless explicitly requested, except for the Flowtend env file above when the user asked for reusable token setup. - Treat any older ~/.claude/plugins/flowtend mirror as optional legacy compatibility plumbing, not the default Claude result. ## Skill Variants ### Create flowtend-api Use this when the user wants to operate a live Flowtend project through a hosted or private API. - Codex path: ~/.codex/skills/flowtend-api/SKILL.md. - Claude Code path: ~/.claude/skills/flowtend-api/SKILL.md. - REST-first for live project operations. - Use only project-scoped routes under /v1/projects/{project_id}/... - Keep auth explicit through FLOWTEND_API_* env vars. ### Create flowtend-cli Use this only when the user explicitly asks for repo-local CLI behavior or OSS-compatible command examples. - Codex path: ~/.codex/skills/flowtend-cli/SKILL.md. - Claude Code path: ~/.claude/skills/flowtend-cli/SKILL.md. - Run from apps/flowtend. - Prefer npm run flowtend:cli -- ... --json. - Warn that missing API env can make the CLI fall back to in-memory. ## Required Environment - FLOWTEND_API_BASE_URL (defaults to https://api.ppippi-lab.site unless another deployment is targeted) - FLOWTEND_API_PROJECT_ID - FLOWTEND_API_KEY (personal access token, usually scoped to this project) ## Stable Routes - `GET /v1/projects` - `POST /v1/projects` - `GET /v1/projects/{project_id}/tasks` - `GET /v1/projects/{project_id}/tasks/all` - `POST /v1/projects/{project_id}/tasks` - `GET /v1/projects/{project_id}/tasks/{task_id}` - `PATCH /v1/projects/{project_id}/tasks/{task_id}` - `DELETE /v1/projects/{project_id}/tasks/{task_id}` - `POST /v1/projects/{project_id}/tasks/{task_id}/advance` - `POST /v1/projects/{project_id}/tasks/{task_id}/child-task-tree/preview` - `POST /v1/projects/{project_id}/tasks/{task_id}/child-task-tree/apply` - `POST /v1/projects/{project_id}/approvals` - `GET /v1/projects/{project_id}/workflow/summary` - `GET /v1/projects/{project_id}/tasks/{task_id}/artifacts` - `GET /v1/projects/{project_id}/usage` ## Shipped Routes Outside The Default Surface - `GET /v1/projects/{project_id}/board` - `POST /v1/projects/{project_id}/tasks/{task_id}/move` - `GET /v1/projects/{project_id}/audit-export` ## Role Rules - A project-scoped PAT only works for its saved projectId. Task create, advance, and move writes flow through the same key. - PATCH task updates are partial: omitted fields keep their current value, while null or empty values clear mutable fields. - DELETE task removes only Draft, Backlog, Blocked, Needs Changes, or Done tasks that do not block dependents. - Planning agents must preview child task trees before approval. Operators use child-task-tree/apply with decision approve or reject; reject creates no tasks. - Review approvals and rejects also use the same PAT. - Both approve and reject decisions go through POST /v1/projects/{project_id}/approvals with the appropriate decision value. A reject decision sends the task back to Backlog. - Do not try to approve or reject through /advance. - When the prior Validation artifact was recorded before the PR merged, approvals can carry fresh repository evidence in the same call. Add repositoryEvidence to the POST /v1/projects/{project_id}/approvals body with the same fields content.repositoryGate accepts on the original handoff (status, mergeable, mergeStateStatus, headSha, verifiedHeadSha, failingChecks, summary). The server records it as a new Validation artifact under the compatibility QA-stage field before re-evaluating the gate; gate rules are unchanged. ## Review Packet Fields - content.schemaVersion should be flowtend.evidence.v1 for structured handoff records. - content.implementationSummary lists the concrete code, docs, config, or test work completed. - content.designChanges is optional and captures UI/design before-and-after notes with surface, before, after, and reason. - content.reviewCheckpoints names the exact points the reviewer should inspect before approving. - content.feedbackPlan explains how send-back feedback should drive the next implementation pass, or what approval means when evidence is clean. - Rejected Review decisions record content.reworkRequest with requestedChanges and the source checkpoints/design context that the next agent should address. - Keep repository links and repositoryGate in content.repository so the Review UI can link the PR/commit and block stale or failing evidence. ## Credential Handoff - Before asking the user, check the current FLOWTEND_API_* env. If missing, source the runtime-native env file when it exists: ~/.codex/.flowtend/project-.env for Codex or ~/.claude/.flowtend/project-.env for Claude Code. - If the runtime-native env file is missing, you may source the other runtime's Flowtend env file for the current run only, but do not write new credentials there unless the user explicitly asks. - If the reusable env file is missing, fall back to the legacy plugin env at ~/.claude/plugins/flowtend/skills/flowtend-api/.env. for the current run only; do not create new files under that legacy path. - Only if all of the above fail, ask the user for the token value. Save received tokens immediately to the reusable env file without echoing the value. - When the user wants reusable setup, write only the current FLOWTEND_API_* env vars to the runtime-native env file (~/.codex/.flowtend/project-.env or ~/.claude/.flowtend/project-.env; shell-sourceable: "export KEY=value"). - Load the selected env file with: set -a; . ; set +a - Use the project-scoped FLOWTEND_API_KEY for the selected FLOWTEND_API_PROJECT_ID. - Never write raw secrets into SKILL.md, logs, or normal output. ## Stable Operating Order 1. Confirm the base URL, project name when available, project id for API routing, and intended action. 2. If live credentials are missing, ask the user for the token value and save it immediately to the reusable env file without echoing. 3. If reusable setup is requested, load or update the runtime-native env file (~/.codex/.flowtend/project-.env for Codex, ~/.claude/.flowtend/project-.env for Claude Code). 4. Export Flowtend env vars explicitly. 5. Check GET /health before write operations. If health fails, stop before any write, surface the failing base URL to the user, and do not retry silently. 6. Build API="${FLOWTEND_API_BASE_URL}/v1/projects/${FLOWTEND_API_PROJECT_ID}". 7. If claiming a Backlog task for In Progress implementation with action=start_dev, include the active worktreePath in the same request. worktreePath is the absolute filesystem path of the worktree the agent will actually work in (e.g. /Users/you/repo/.worktrees/). 8. Call the project-scoped route. 9. Verify writes with a cheap follow-up GET (/tasks/{id}, /tasks, or /workflow/summary). 10. On 401/403, re-check the PAT, project id, and whether the user still has access to this project before retrying. On 409/422, re-read task state before retrying — do not blindly repeat the same write. On 5xx, retry at most once after a short pause, then stop and report. 11. For backlog-clearing runs, refresh /tasks or /workflow/summary after each finished task, treat refreshed actionable tasks as the current backlog, and continue until no actionable backlog tasks remain. ## Workflow Rules - Default: Draft -> Backlog -> In Progress -> Validation -> Review -> Done - Validation off: Draft -> Backlog -> In Progress -> Review -> Done - Validation off, Review off: Draft -> Backlog -> In Progress -> Done ## Workflow Stages - Draft: Capture or prepare the task before it enters the board. - Backlog: Ready for an agent or operator to start. - In Progress: Implementation work is actively underway. - Validation: Checks and validation evidence are being produced. (validation optional) - Review: Human approval or send-back decision. (review optional) - Done: Work is completed. Send-back path: `Review -> Backlog`. Reviewer send-back returns the task to Backlog for another implementation pass. ## Repository Completion Policy - If repo review is enabled, default completion is a pushed branch plus an opened PR. - If repo review is disabled, default completion is commit -> main reflection -> main push. - Do not stop at reviewed when the real terminal state is PR creation or main push. - Do not add a separate test stage to the default prompt; keep verification inside implementation and validation guidance. - Do not tell agents to add Flowtend task ids, task slugs, project ids, or Flowtend-internal metadata to commit messages, PR titles, or PR bodies unless the user explicitly requests that metadata. - Keep commit and PR text focused on the change summary, scope, and validation results. - To detect the project's workflow configuration, call GET /v1/projects/{project_id}/workflow/summary and match the returned stage enablement against the supported paths below. If the summary is unavailable, ask the user which stages are enabled before finishing the prompt. Examples: - Review on: Finish with the branch pushed and a PR opened. - Review off: Finish with the change committed, reflected on main, and pushed. ## Backlog Clearing Policy - Treat backlog-clearing as a loop, not a single-task assignment. - Finish one actionable task through the project's real terminal condition, refresh the backlog, and immediately continue with the next actionable task. - An "actionable" task is one whose stageLabel is Backlog or kanbanStage is backlog, with no active claimedBy/worktreePath ownership, and with every blockedByTaskIds entry already done. - When available, use workflow/summary dependencyPlanning.runnableBacklogTasks as the low-token next-unblocked work set; blockedBacklogTasks explains unmet blockers and cycles surfaces impossible dependency chains. - When the summary path is unavailable, fall back to GET /tasks?view=agent (auto-filters to backlog discovery statuses) or GET /tasks?view=compact, and only fetch full task bodies and artifacts after the actionable set is narrowed. - Skip tasks where claimedBy is set by another actor, worktreePath points at a different worktree, or any blockedByTaskIds entry is not yet completed, unless the user explicitly asks to take them over. - A refreshed backlog count changing or growing is not a blocker by itself. Treat the refreshed actionable set as the current backlog and keep going. - Do not stop only to give an intermediate summary while actionable backlog tasks still remain. - Stop only when no actionable backlog tasks remain, the user explicitly interrupts, or a real blocker prevents safe continuation. Example prompt: Keep draining the Flowtend backlog: work one actionable task at a time in a dedicated worktree, finish each task through main push and deployment verification, refresh the project task list, treat newly returned actionable tasks as part of the same run, and continue until no actionable backlog tasks remain. ## Done Criteria - Create or update exactly one skill folder under the current runtime root: ~/.codex/skills// for Codex or ~/.claude/skills// for Claude Code. - If the user asked for reusable auth setup, write exactly one project-scoped env file under the current runtime path (~/.codex/.flowtend/project-.env or ~/.claude/.flowtend/project-.env). - Write a valid SKILL.md with name and description frontmatter. - Keep the body concise, operational, and Flowtend-specific. - Default to flowtend-api unless the user explicitly asks for flowtend-cli. ## Do Not Create - Do not create README.md, CHANGELOG.md, setup notes, or helper files unless explicitly requested. The only allowed extra file is the runtime-native Flowtend env file (~/.codex/.flowtend/project-.env or ~/.claude/.flowtend/project-.env) when the user asked for reusable token setup. - Do not invent legacy global routes such as /tasks or /approvals. - Do not echo secrets back in the skill output or summary, and do not write secrets into SKILL.md. - Do not silently convert a CLI-only request into a REST-first skill. ## Output Expectations - Report whether the skill was written for Codex or Claude Code and which SKILL.md path was used. - Report which base URL and project name the skill assumes; mention the project id only when the user asks for it, an API route needs it, or disambiguation is required. - Report that the skill uses FLOWTEND_API_KEY without echoing the secret. - If reusable credential setup ran, report the runtime-native env file path that was updated without echoing the secret. - For write flows, report the task title and resulting status. Include the stable task id only when the user asks for it, an API route needs it, or disambiguation is required. - In human-facing summaries, lead with the task title or title-derived reference. Do not use the raw task id as the task's name. - In human-facing summaries, lead with the project name when known. Do not use the raw project id as the project's name. - Say explicitly when verification did not run, including when /health failed and writes were skipped. - On REST failures, report the HTTP status and which recovery action the skill took (401/403 credential recheck, 409/422 state re-read, 5xx single retry then stop). ## Response Examples - Task selection: Selected "Task evidence timeline UI 추가" for Flowtend. - Progress update: Working on "Task evidence timeline UI 추가" in Flowtend; status is In Progress. - Review response: Approved "Task evidence timeline UI 추가" in Flowtend; status is now Done. ## Template Checklist - The skill folder contains exactly one required file: SKILL.md. - The frontmatter includes both name and description. - The body points agents to the raw Markdown skill-authoring contract before route-sensitive work. - The body tells the agent to check health before writes. - The body preserves immutable safety rules: no secret echoing, project-scoped routes only, and follow-up read verification. - The body includes only a small offline fallback route set instead of a full static route catalog. ## REST Quickstart ```bash export FLOWTEND_API_BASE_URL='https://api.ppippi-lab.site' export FLOWTEND_API_PROJECT_ID='42' export FLOWTEND_API_KEY='' API="${FLOWTEND_API_BASE_URL}/v1/projects/${FLOWTEND_API_PROJECT_ID}" AUTH="Authorization: Bearer ${FLOWTEND_API_KEY}" curl -sf "${FLOWTEND_API_BASE_URL}/health" curl -fsS \ -H "$AUTH" \ "${API}/tasks" ``` ## SKILL.md Template ```md --- name: flowtend-api description: Use when the user wants to operate a live Flowtend project through the project-scoped REST API. Loads the public Flowtend docs contract first, then applies local auth, health-check, and safety rules. --- # Flowtend API Use this skill for live Flowtend project operations through the project-scoped REST API. This SKILL.md is a bootstrap, not the full API contract. ## Use This Skill When - The user wants to inspect or mutate a running Flowtend project. - The user wants the current project-scoped REST contract. - The user did not explicitly ask for CLI-only or OSS-compatible behavior. ## Live Contract Sources Before route-sensitive or workflow-sensitive work, load the primary raw Markdown contract: - https://flowtend.ppippi-lab.site/docs/skill-authoring.md Use https://flowtend.ppippi-lab.site/docs/skill-authoring only when a human-readable rendered page is better. The public Markdown contract wins over this installed SKILL.md for route names, workflow paths, evidence schemas, and shipped automation details. Use repo-local docs only when the private repository is already checked out and directly relevant. ## Working Rules - Require FLOWTEND_API_PROJECT_ID. Default FLOWTEND_API_BASE_URL to https://api.ppippi-lab.site unless another deployment is targeted. - Prefer Authorization: Bearer ... - Before asking the user, check the current FLOWTEND_API_* env, then source the runtime-native Flowtend env file (~/.codex/.flowtend/project-.env for Codex, ~/.claude/.flowtend/project-.env for Claude Code), then optionally source the other runtime's env file for the current run only, then fall back to the legacy plugin env file for the current run only. Only if all fail, ask the user for the token value and save it immediately to the runtime-native reusable env file without echoing. - When the user wants reusable setup, store the current FLOWTEND_API_* env vars in the runtime-native Flowtend env file. - Use the project-scoped FLOWTEND_API_KEY for every project-scoped call. - Check GET /health before writes. If health fails, stop before any write and report the failing base URL rather than retrying silently. - Use only /v1/projects/{project_id}/... routes. - Verify writes with a follow-up GET. - Approval and reject decisions go through the approvals route documented by the live contract. Do not use /advance for either unless the live docs explicitly replace that rule. - When claiming a Backlog task for In Progress implementation with action=start_dev, include the absolute worktreePath in the same request so Flowtend can track the claim. - On 401/403, re-check the PAT, project id, and project access before retrying. On 409/422, re-read task state before retrying. On 5xx, retry at most once after a short pause, then stop and report. - If the user asks to clear backlog or keep going until no tasks remain, repeat task selection -> claim -> implement -> verify -> main push/deploy verification -> task refresh until no actionable backlog tasks remain. - Treat a task as actionable only when stageLabel is Backlog or kanbanStage is backlog, claimedBy and worktreePath are unset, and every blockedByTaskIds entry is done. - Do not stop because the refreshed backlog count changed or new actionable tasks appeared. - Do not stop only to report intermediate progress while actionable backlog tasks still remain. - Do not add Flowtend task ids, task slugs, project ids, or Flowtend-internal metadata to commit messages, PR titles, or PR bodies unless the user explicitly requests that metadata. - Keep commit and PR text focused on the change summary, scope, and validation results. - Never write raw secrets into SKILL.md or normal output. ## If Public Docs Cannot Be Reached Do not invent routes. Use only this fallback surface, always under API="${FLOWTEND_API_BASE_URL}/v1/projects/${FLOWTEND_API_PROJECT_ID}": - GET /workflow/summary - GET /tasks?view=agent - GET /tasks?view=compact - POST /tasks - GET /tasks/{task_id} - PATCH /tasks/{task_id} - POST /tasks/{task_id}/advance - POST /approvals - GET /tasks/{task_id}/artifacts Fallback writes still require GET /health first and a follow-up read after the write. If a needed operation is outside this fallback set, ask for the current docs or stop with the missing contract detail. ## Low-Token Discovery - Start every task scan with GET /v1/projects/{project_id}/workflow/summary; dependencyPlanning.runnableBacklogTasks is the low-token next-unblocked work set, blockedBacklogTasks explains unmet blockers, and cycles surfaces impossible dependency chains. - For task list scans, pass view=agent (auto-filters to backlog discovery statuses) or view=compact (compact metadata) instead of the default full task body. Default GET /tasks is paginated; only call GET /tasks/all when a complete dataset is intentionally needed. - Use statuses= with view=compact when narrowing to a specific stage (e.g. dev_running for active work checks). - Fetch GET /v1/projects/{project_id}/tasks/{task_id} or /tasks/{task_id}/artifacts only after the actionable set is narrowed. ## Stable Order 1. Load the public Markdown skill-authoring contract. If that fails, explicitly switch to the fallback surface above. 2. Confirm the base URL, project name when available, project id for API routing, and intended action. 3. Check current FLOWTEND_API_* env, then source the runtime-native Flowtend env file, then optionally the other runtime's env file, then the legacy plugin env file for the current run. Only if all fail, ask the user for the token value. 4. Load or update the runtime-native Flowtend env file when reusable setup is requested. 5. Export Flowtend env vars explicitly. 6. Check API health before writes. On failure, stop before any write and report. 7. Build API="${FLOWTEND_API_BASE_URL}/v1/projects/${FLOWTEND_API_PROJECT_ID}". 8. If claiming a Backlog task for In Progress implementation, include the absolute worktreePath in the start_dev request. 9. Execute the documented REST call. 10. Verify writes with a cheap read. Apply the 401/403, 409/422, 5xx rules from Working Rules on error. 11. For backlog-clearing runs, refresh the project task list or summary after each finished task, treat refreshed actionable tasks as the current backlog, and continue until no actionable backlog tasks remain. ## Output - Report the base URL and project name used, but never echo secrets. Mention the project id only when the user asks for it, an API route needs it, or disambiguation is required. - Report that the request used FLOWTEND_API_KEY without echoing the secret. - If reusable credential setup ran, say which runtime-native env file was updated without echoing the secret. - For writes, include the task title and resulting status. Include the stable task id only when the user asks for it, an API route needs it, or disambiguation is required. - If an implementation task was claimed, report claimedBy, claimedAt, and worktreePath. - In human-facing summaries, lead with the task title or title-derived reference. Do not use the stable task id as the task's name. - In human-facing summaries, lead with the project name when known. Do not use the raw project id as the project's name. - Say explicitly when verification did not run, and why. ``` ## Authoritative Sources - https://flowtend.ppippi-lab.site/docs/skill-authoring.md - https://flowtend.ppippi-lab.site/docs/skill-authoring