qfai-configure

name	qfai-configure
title	QFAI Configure (Tune qfai.config.yaml)
description	Analyze the repository and tune qfai.config.yaml (testFileGlobs, exclude globs, optional specSections).
argument-hint	[--auto]
allowed-tools	["Read","Glob","Write","TodoWrite","Task"]
roles	["orchestrator","delivery-planner","qa-strategist","devops-ci-engineer","completion-reviewer","qa-gatekeeper"]
routing-profile	runtime-heavy
mode	evidence-focused

/qfai-configure - Configure QFAI for this repository

[DRIFT-PROTOCOL:MANDATORY]

User Questions (AskUserQuestion Protocol)

Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#user-questions-askuserquestion-protocol.

Skill-specific examples:

• configuration decisions
• glob pattern confirmation

FORMAT SSOT (Mandatory)

• Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#format-ssot-mandatory.

• Before writing or editing any .qfai/** artifact, read the relevant skill-local reference or template:

  • .qfai/assistant/skills/qfai-discussion/references/discussion-artifact-rules.md
  • .qfai/assistant/skills/qfai-sdd/references/spec-traceability-rules.md
  • .qfai/assistant/skills/qfai-sdd/references/contract-artifact-rules.md
  • .qfai/assistant/skills/qfai-prototyping/references/evidence-requirements.md

Inputs Priority (Preflight)

When unsure, read inputs in this order:

• P1: .qfai/assistant/constitution/*
• P2: .qfai/assistant/manifest/* + .qfai/assistant/catalog/*
• P3: .qfai/specs/<spec-id>/09_delta.md (Decision Records; if no spec yet, state "not applicable")
• P4: other artifacts (01_Spec.md, contracts, evidence, optional legacy scenario.feature / coverage ledgers)

Sub-agent Delegation (MANDATORY)

Follow .qfai/assistant/constitution/shared-skill-delegation-baseline.md.

Orchestrator Protocol (MUST)

• No additional overrides.

Capability Probe (MUST)

• No additional overrides.

Delegation Failure (Hard Stop)

• No additional overrides.
• Do not simulate roles. If the first required delegation fails, stop the stage and report remediation.

Work Orders Summary (MANDATORY evidence)

Use the shared schema.

Stage Minimum Roles (MUST)

• Delegate: PrimaryAuthor create first drafts of major artifact drafts for this stage.
• Integrate: Orchestrator consolidates delegated outputs and presents them to the user for confirmation.
• Gate: Reviewer is delegated independently and returns only PASS or REVISE.
• Orchestrator must not draft the primary artifact body and must not self-approve.

Reviewer Gate (MUST)

• Follow .qfai/assistant/constitution/shared-skill-delegation-baseline.md#reviewer-gate-baseline.
• Reviewer checks:
  • required roles were delegated;
  • doctor evidence exists: qfai doctor --fail-on error completed without failing checks;
  • Drift Protocol enforced;
  • test-layer policy enforced against .qfai/assistant/catalog/test-layers.md;
  • tool-count heuristics are signals, not gates.
• Route specialist reviewers from .qfai/assistant/manifest/agent-routing.yml.
• Default configure review set:
  • completion-reviewer
  • qa-gatekeeper
• Do not declare DONE or handoff until all routed blocking reviewers return PASS.

Work order template (copy/paste)

Use the shared template.

Reviewer response template

Use the shared template.

• Required field: Status (PASS/REVISE).

Stage 0 — Steering completion refresh (mandatory)

Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#stage-0---steering-completion-refresh-mandatory.

• Fill steering from verifiable repository evidence first; when evidence is missing, mark the field TBD and record the gap in the evidence file.

Delta Rejected Guard (Mandatory)

Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#delta-rejected-guard-mandatory.

CRITICAL CONSTRAINTS (Read First)

• Only update qfai.config.yaml, .qfai/assistant/manifest/* + .qfai/assistant/catalog/*, and .qfai/evidence/configure-<run-id>.md unless explicitly asked.
• You MUST produce the required evidence file: .qfai/evidence/configure-<run-id>.md.
  • .qfai/evidence/ is intentionally NOT tracked by Git (it ships with a local .gitignore).
  • Do NOT commit evidence files; summarize key outcomes in the PR description instead.
• You MUST run the mandatory checks listed below and record outcomes.
• You MUST stop and escalate if tooling choices or runnable path remain ambiguous.
• Completion must be approved by a reviewer who did not modify the config.

Completion Contract (Shared)

Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#completion-contract-shared. Follow .qfai/assistant/constitution/shared-skill-operating-baseline.md#gate-failure-autorepair-protocol for validate, doctor, and quality-gate failures.

Goal

Analyze the repository and update qfai.config.yaml so traceability checks are actionable, with a documented minimum runnable path.

Note: /qfai-sdd includes a preflight step that bootstraps missing config/steering when run directly after init. /qfai-configure remains the recommended way to tune qfai.config.yaml early with a clean, minimal diff.

Success Criteria (Definition of Done)

• qfai.config.yaml is updated with a minimal diff focused on traceability globs.
• validation.traceability.testFileGlobs reflects the real test layout.
• validation.traceability.testFileExcludeGlobs is added only when needed.
• If strict spec sections are explicitly requested, validation.require.specSections is updated with a minimal, evidence-based list.
• A validation checklist with evidence (sample matched files) is produced.
• Steering files (product.md, tech.md, structure.md, manifest.md) are filled or refreshed with evidence, or marked TBD when evidence is missing.
• Evidence file exists: .qfai/evidence/configure-<run-id>.md.
• Completion is approved by a reviewer who did not modify the config.

Mandatory checks

• Tool selection rationale is recorded (per layer if applicable).
• A minimum runnable path is described (dev server, db, env, commands).

Not-done criteria

• Tool selection rationale missing.
• Minimum runnable path missing or unverifiable.

Evidence (MANDATORY)

Create and update: .qfai/evidence/configure-<run-id>.md Use <run-id> as a short date stamp (e.g., 2026-01-28) or a short slug for this run.

Evidence must include:

• chosen tools per layer (E2E/API/Integration/Component/Unit)
• commands to run locally

Required sections

• Objective
• Inputs reviewed (files/paths)
• Decisions made (with rationale)
• Work performed (what changed, where)
• Commands executed + key outputs
• Gaps / Open risks (must be explicit; "none" is acceptable if justified)
• Final status (PASS/FAIL) + who confirmed

Template

# Configure Evidence: <run-id>

## Objective

## Inputs reviewed (files/paths)

## Decisions made (with rationale)

## Work performed (what changed, where)

## Commands executed + key outputs

## Proposed globs

- include:
- exclude:

## Evidence samples (5-15)

## Tool selection (per layer)

## Minimum runnable path

## Files changed

- qfai.config.yaml:
- steering files:

## Gaps / Open risks

## Final status (PASS/FAIL) + who confirmed

Non-Negotiable Principles (QFAI Articles)

These principles are inspired by "constitution / articles" patterns used by other agent frameworks, but tailored to QFAI.

1. SDD First (Specification is the source of truth)
   If there is a conflict between code and spec, treat the spec as authoritative and either (a) fix code or (b) raise an explicit Open Question to change the spec.

2. Traceability is mandatory
   Every meaningful change must be traceable: Require -> Spec -> Scenario -> Tests -> Code -> Verification evidence.

3. Evidence over confidence
   Prefer observable proof (logs, commands, file diffs, test results). If you cannot verify, say so and record it.

4. Minimize scope, but never hide gaps
   Keep changes minimal, but do not "paper over" missing decisions. If something blocks correctness, stop and ask.

5. Quality gates are the decision mechanism
   Use tests/lint/typecheck/build/pack verification (whatever the repo defines) as the primary guardrail. Fix until PASS.

6. Make it runnable
   Outputs must be executable in terminal/CI. Provide copy-paste commands.

7. User time is expensive
   Ask only the questions that are truly blocking. Everything else: make reasonable assumptions and label them clearly.

README Rule

Do not create .qfai/**/README.md files as scaffold or format documentation; keep artifact guidance in skill references/templates.

• READMEs are reference guides. Follow their structure, templates, and checklists.

Absolute Rule - Output Language

All outputs MUST be written in the user's working language for this session.

• If the user writes in Japanese, output Japanese.
• If the user writes in English, output English.
• If the user mixes languages, prefer the dominant language unless explicitly instructed otherwise.
  This rule overrides all other stylistic preferences.

Multi-Role Orchestration (Subagents)

Use the platform's native sub-agent delegation mechanism for Claude Code, GitHub Copilot, and Codex.

Delegation order

Use .qfai/assistant/manifest/agent-routing.yml as the routing SSOT.

• First required delegation / Capability Probe: delivery-planner in the analysis phase.
• Then follow routed phases in order: analysis (delivery-planner, qa-strategist) -> config (devops-ci-engineer) -> review (completion-reviewer, qa-gatekeeper).
• Do not prepend non-routed roles before the first required delegation attempt.

Delegation contract (tool-neutral)

Role: delivery-planner
Task title: Analyze repo and propose testFileGlobs
Goal: Tune qfai.config.yaml with a minimal diff
Inputs:
- relevant steering and repo layout
Constraints:
- minimal diff
- evidence-first
Return:
- proposed globs + rationale + evidence refs

Failure rule

• The first required delegation attempt doubles as the capability check.
• If that delegation fails, stop immediately. Do not simulate roles or continue with self-execution.

Completion Separation (mandatory)

• Config changes (devops-ci-engineer) and completion approval (completion-reviewer) must be separate.
• qa-gatekeeper must confirm evidence sampling before approval.

Context Refresh (mandatory for long tasks)

Every 5 major actions, pause and restate:

• DoD and prohibited "done" criteria
• Evidence samples collected vs missing
• Config changes and steering updates completed

Constraints

• Only update qfai.config.yaml, .qfai/assistant/manifest/* + .qfai/assistant/catalog/*, and .qfai/evidence/configure-<run-id>.md unless explicitly asked.
• Do not modify tests or source code.
• Avoid overly broad globs (e.g., **/*).
• Exclude generated/output directories (node_modules, .git, .qfai, dist, build, coverage, .next, out, etc.).
• Keep validation.require.specSections unchanged unless the user explicitly requests strict required headings.

Step 0 - Load Context (always)

1. Read relevant project steering (if present):

   • .qfai/assistant/catalog/structure.md
   • .qfai/assistant/catalog/tech.md
   • .qfai/assistant/catalog/product.md
   • any additional files under .qfai/assistant/{manifest,catalog}/

2. Read project constitution / instructions (if present):

   • .qfai/assistant/constitution/constitution.md
   • .qfai/assistant/constitution/workflow.md (or equivalent)

3. Inspect repo conventions:

   • package manager (pnpm/npm/yarn), test runner, lint/typecheck scripts, CI definitions
   • existing test patterns (unit/integration/e2e)

4. Inspect steering templates and placeholders:

   • .qfai/assistant/catalog/product.md
   • .qfai/assistant/catalog/tech.md
   • .qfai/assistant/catalog/structure.md
   • .qfai/assistant/catalog/manifest.md

Step 0 - Project Analysis (mandatory)

Before editing config, thoroughly analyze the current project:

• background and goals
• directory structure and conventions
• chosen technologies and versions (runtime, package manager, test runner)
• test locations (unit/integration/e2e)
• existing test naming rules (*.test.*, *.spec.*, *_test.*, etc.)

If analysis cannot be performed (missing access), clearly state what could not be verified and proceed with minimal-risk assumptions.

Step 1 - Identify test frameworks and locations

1. Inspect package.json and config files (e.g., vitest.config.*, jest.config.*, playwright.config.*, pytest.ini, go.mod).
2. Enumerate directories that contain tests (e.g., tests/, src/, e2e/, integration/).
3. Note naming rules and extensions that indicate test files.
4. If strict spec sections are requested, sample existing 01_Spec.md files and list H2 headings used.

Step 2 - Propose glob patterns

Provide 3-10 include globs that cover all known test locations:

• Prefer explicit patterns (e.g., src/**/*.test.ts, tests/**/*.spec.ts).
• Include src-colocated tests if they exist.

Provide exclude globs only when necessary (beyond the default exclusions).

Step 3 - Update steering (evidence-first)

Fill steering templates with repo evidence.

• Keep existing content when already accurate.
• When evidence is missing, write TBD and record what is missing.
• Do not invent facts.
• For steering/manifest.md, explicitly record Evidence and Assumptions (if evidence is missing).

Step 4 - Update qfai.config.yaml (minimal diff)

Edit:

• validation.traceability.testFileGlobs
• validation.traceability.testFileExcludeGlobs (only if needed)
• validation.require.specSections (only if explicitly requested)

Keep all other config keys unchanged.

Step 5 - Evidence sampling

Sample 5-15 actual test files that match the proposed globs.

• If zero matches exist, stop and ask for clarification.
• If some directories are ambiguous, list them as Open Questions.

Checkpoints

• Repository analysis completed (frameworks, test layout, naming rules).
• Steering files updated with evidence or TBD.
• Manifest includes evidence and assumptions (or TBD).
• Proposed include/exclude globs with rationale.
• qfai.config.yaml updated (minimal diff).
• Optional: specSections tuned when requested (or kept empty).
• Evidence: sample matched files listed.

Output

Provide:

1. Updated qfai.config.yaml (diff or full file, as appropriate).
2. Updated steering files (diff or summary).
3. A short summary of changes and rationale.
4. Validation checklist with sampled files.
5. If specSections updated, list the chosen headings and evidence source.
6. Open questions (blocking vs non-blocking).

Suggest next step: /qfai-discussion (or rerun /qfai-configure if configuration is not ready).

DONE Declaration (Mandatory Output)

When you declare DONE, include:

• Referenced inputs: instructions/steering and the 09_delta.md spec-id
• DR-IDs referenced (or "none" + propose adding a Decision Record)
• Confirmation that no rejected options were reintroduced (or list RE-OPEN DR-IDs)

FINAL CHECKLIST (Check Last)

• CRITICAL CONSTRAINTS were followed.
• Evidence file exists and is complete.
• All mandatory checks were executed and recorded.
• No untracked gaps remain (or they are explicitly documented).
• Completion approved by a reviewer who did not modify the config.

Completion Checklist (MUST)

• This skill's Definition of Done is satisfied.
• Required artifacts were produced or updated (if applicable).
• Open questions were logged to the proper OQ file (if applicable).
• The completion message was presented to the user.
• Next actions were enumerated for all available options.

Completion Message & Next Actions (MUST)

When this skill is complete, provide a final user-facing completion message and enumerate all actionable next steps.

• Proceed (recommended): /qfai-discussion. Action: run it to formalize requirements from the configured project context.
• Discussion needs more input: rerun /qfai-discussion. Action: collect missing scope, constraints, and assumptions first.
• Configuration needs refinement: rerun /qfai-configure. Action: provide additional include/exclude evidence and update qfai.config.yaml.

Default Autopilot Policy

The skill collapses avoidable per-session prompts to 0-1 by classifying every decision into one of three named buckets:

• auto-decide:
  • output formatting
  • ID / sequence numbering
  • append-vs-create on subject overlap
  • equivalent-option pick
• ask-user:
  • CREATE / DELETE / SPLIT / MERGE / SUPERSEDE / UPDATE:REMOVE triage operations (each with a prompt template that names the target and rationale)
  • destructive operations (rm / overwrite / force-push)
  • version-pin changes (package.json#version, branch pin)
  • scope expansions outside the active envelope
• hard-required:
  • companyName
  • brand intent
  • primarySpecId (when absent from inputs)

A skill MAY narrow the auto-decide bucket (drop entries) but MUST NOT widen it. Widening triggers a Reviewer-Gate finding.

project_memory:

• qfai-configure is the user-facing entrypoint for editing qfai.config.yaml and the .qfai/assistant/manifest/ declarative manifests; edits to those files MUST go through this skill so the agent-catalog / agent-routing / review-profiles SSOTs stay consistent.
• Run after every major workflow change to refresh the consuming project to the current QFAI baseline. Do NOT edit qfai.config.yaml directly when the skill is available.