What does Project Steward do?

Role and Routing

Project Steward stores reusable governance methods across projects. The project's own product decisions, architectural facts, and long-term constraints remain in the project's existing sources of truth; mutable tool facts for users and machines remain in environment profiles outside the project and Skill.

Select the primary path based on the outcome the user wants to achieve; independent outcomes within the same request are separately accounted for:

Conversation history, corrections, full implementation process, or target Skill boundary: conversation learning and self-evolution.
Before starting functionality, refactoring, migration, or cross-layer changes to eliminate rework: change prevention.
Defects, partial migration, repeated fixes, real link failures, or checks for cohesion, coupling, duplication, god modules: root cause remediation.
Checks, integration, or fixes for project compatibility with external CLI, execution tools, or protocols: external tool compatibility.
Understanding the purpose, architecture, and capabilities of a repo, directory, or source package, or studying a reference project: project research and explanation.
Inventorying or organizing a project directory, determining real usage, generation status, ignore, move, archive, and delete boundaries: repository directory governance.
Establishing, adopting, upgrading, or checking project templates: project baseline and templates.
Writing stable defaults into templates: template evolution.
Defining, reviewing, rebuilding, or implementing product experience and interfaces: product experience and interface governance.
Auditing, rewriting README, or creating visually enhanced GitHub profile: README and homepage.
Governing project logs, LLM records, long-term memory, TTS, or log viewing results: humane logging.
Initializing Git, creating a repo, committing, pushing, changing visibility, or verifying remote: repository creation and publication.
Selecting, applying, or batch-managing licenses and third-party attributions: license governance.
Establishing or consuming user environment profiles, checking tools, caches, SDKs, terminals, or long-running tasks: user environment profile and execution environment.
Item-by-item verification of implementation plan completeness, or full check, project health assessment, and project-level risk arrangement: comprehensive project audit.

When only the Skill is named, select the most matching path based on available materials; if sufficient materials are lacking, provide a direct request example that fits the context and stop.

After the primary path is selected, establish a routing ledger before any project write or special implementation: user final outcome, primary path, fixed mandatory methods, conditional specials with their triggering evidence, action thresholds, official consumers, acceptance criteria, and stopping points. Fixed mandatory methods cannot be skipped even if a local modification appears obvious; conditional specials are only applied when applicable evidence is obtained. When acceptance criteria are later added to the same request, update the original ledger; do not replace still-valid scope with the latest symptom.

Common Boundaries

Ordinary business functionality remains the responsibility of the current development task; when the user only asks for an explanation of a single error, function, or local behavior, stop after answering that result, without escalating to a project-level transformation. Only enter the corresponding path when the request itself calls for prevention, governance, migration, self-evolution, or project-level outcomes.
Upon path selection, immediately freeze scope, write permissions, and stopping points. Checks, audits, diagnostics, evaluations, analyses, reviews, and reports are read-only by default; write permissions are only granted when the same request explicitly requires fixing, governing, implementing, modifying, updating, or self-evolving.
If the user provides source code archives and asks to understand, audit, or research the project, or only names the Skill and attaches the archive, decompression is material preparation for entering read-only research, not a formal project write. Follow "Project Research and Explanation" directly to determine the target root, decompress using existing scripts to an independent name-conflict-avoiding directory, read the script-returned project root, and continue with read-only research, without requiring additional confirmation for decompression. This action only authorizes the creation of a research copy and reading its contents; running the project, installing dependencies or decompression tools, modifying the project, moving or deleting original files, committing, and publishing are separately authorized.
Networking, downloading, installing, running, generating, writing, moving, archiving, deleting, committing, pushing, and publishing are separately authorized; only the default completion contracts explicitly listed in this section may merge write, commit, push, and remote acceptance within the same user outcome. Running or generating does not equate to obtaining project write permissions; outside the default completion contracts, commit, push, or publish only authorize processing already existing and accurately verified changes, without retroactively authorizing prior writes and without including irrelevant working tree changes.
When the user explicitly names Project Steward (including via $project-steward) and explicitly requests modification, fixing, governance, updating, or optimization of an existing Git project, if the current branch has a configured upstream and the user has not requested only local changes, no commit, no push, or an earlier stopping point, this round of implementation defaults to completion as follows: verify by approved dependency closure, precise commit, non-force push of the current tracking branch, then check remote HEAD and key consumers; do not ask a second time whether to push after local verification. Read-only requests, implicit routing, no upstream, remote creation, visibility changes, deletion, force push, history rewriting, packaging, deployment, and irrelevant working tree changes are not authorized by this default; stop in accordance with references/repository-publication.md in cases of forks, unverified changes, unauthorized deletion, credential, verification, or authentication failures.
When the user confirms a Project Steward self-evolution plan and has not requested only local changes, the existence of a current tracking remote defaults to treating the entire current workspace as an indivisible publication scope: verify all tracked modifications, untracked files, and existing deletions, use git add -A to commit and push the current tracking branch together; if any item cannot be published together, preserve the complete workspace and stop. This default does not authorize remote creation, force push, visibility changes, or implementing new deletions.
When the user explicitly requests integration, fixing, or replacement of Star History for an existing GitHub repository, the confirmation contract defaults to including commit, push, and remote acceptance of the approved dependency closure for this round; unless the user explicitly requests only local changes, do not wait for a second publication authorization after write verification. This default does not include remote creation, force push, visibility changes, deletion, or irrelevant working tree changes.
At the start of each user turn, internal round, automatic re-run, and context compression recovery, before any tool call or state change, recover from the most recent explicit user action the outcomes, scope, permissions, and stopping points that have not yet been completed. Continue only if the same outcome is still undelivered and the scope, affected chain, and permissions remain unchanged; stop and wait for confirmation if a read-only outcome has already been delivered, there is no new explicit action, the user changes the outcome, an unrelated issue arises, or new permissions are required. Audit findings, assistant suggestions, internal plans, goal names, todo lists, and automatic prompts cannot fabricate new outcomes or write permissions.
When extending from a short action to multiple stages, entering a waiting state, or when the evidence state changes, proactively explain the reason for extension, completed checkpoints, current state, the next observable result, and required input; do not repeat notification when state is unchanged, and do not use process explanations to mask scope expansion.
When a new independent request replaces an unfinished outcome, hand over already written or changed objects, existing evidence, unverified user commitments, running processes, residuals, original permissions, and stopping points; the new request does not authorize continuing, reverting, or cleaning up the old outcome.
First freeze the accurate project root, material scope, active files, and real consumers. Use Git only when .git directly exists at the accurate project root and the current path truly requires history, working tree, or publication evidence.
Sources must be read to a clear end; for long files, first obtain line count, byte count, or pagination capability, then read in stable intervals completely. When concurrent changes touch behavioral contracts, affected files, consumers, verification, or user outcomes, old confirmations become invalid; re-plan and re-confirm.
Multiple independent probes are parallelized only when the orchestrator can preserve output, errors, and exit status for each; if any one would cause the entire batch to abort early, execute them independently. After a batch failure, preserve still-fresh success evidence and only re-run items that were shadowed, not executed, or had unknown status.
Write project facts back to the project's single existing source of truth; write environment facts to independent user profiles; only migrate-able governance methods enter the Skill; templates only accept stable defaults that should be executed for every project of a given type.
When judging whether a capability from history or external material already exists, first complete independent outcome splitting and necessary causal ordering, then hide the source and check if the target can recognize the same condition, preserve the same constitutive details, and make the same concrete treatment; only a superior governance framework counts as partially possessing. After completing item-by-item comparison, distill common mechanisms and special dimensions.
Verification selects levels based on change risk: first run targeted checks directly covering the current change and acceptance claims; when only editing documentation, licenses, attributions, or pure metadata, stop after passing the corresponding maintenance entry, without launching unrelated browsers or end-to-end chains; only escalate to full regression and real user chains when public contracts, core runtime, cross-repository boundaries, releases, or targeted checks expose systemic impact.
After a state change, directly read back the authoritative target. Complete verification must follow the chain of formal producers, transmission or storage boundaries, consumers, and user-observable outcomes; do not let consumers hand-write fake data or mock the core link being verified.
Before closing a commitment or declaring completion using test results, the identity of expected key tests must match the unique identity actually collected by the test framework; missing or non-unique identities can only be marked as uncovered.
When reading settings, running reports, structured artifacts, or logs for diagnostics, first project the allowed fields needed for the current judgment according to references/log-audit-standard.md; do not output unknown structures in full recursively, and credentials must be sanitized before entering tool output, conversation, or diagnostic exports.

Conversation Learning and Self-Evolution

First read references/conversation-learning-and-self-evolution.md in full.

When any user outcome contains failure, correction, protection interceptions, temporary workarounds, or residuals, then also read references/root-cause-remediation.md. Reading order is fixed: recover the full process by outcome, determine main learning topics and independent sub-outcomes along the causal hierarchy, then recover specific details that will change future governance and compare target capabilities item by item according to common boundaries, only then distill common mechanisms and special dimensions, judge migratability, functional boundaries, and formal owners, and finally judge historical responsibility. Workarounds and residuals must not cover earlier, evidence-supported controllable root causes; when a subsequent correction changes the main cause, the existing plan and confirmation immediately become invalid. Only when the outcome is successful and these signals are absent, do not load root cause methods.

Capability comparison must first distinguish "missing methods" from "existing methods not being routed, executed, or verified." The former only strengthens the single method owner in place; the latter only fixes the earliest failing main route, action threshold, official consumer, or verification, without adding synonymous rules in other files. Plans are organized by owner and consumption chain, not by stacking patches in the order of conversation appearance.

When the user only requires analysis, remain read-only. When explicitly requesting absorption, self-evolution, update, optimization, or iteration of Project Steward, first deliver future behavior, functional boundaries, representative output, affected files, and verification methods, then stop; only modify the active Skill after the user confirms the plan. When the confirmed plan does not declare only local changes, also read references/repository-publication.md; if the current tracking remote exists, verify the entire workspace by actual impact, use git add -A to commit and push tracked modifications, untracked files, and existing deletions together, and confirm that remote HEAD and workspace are complete before finishing. When remote, authentication, branch protection, fork, verification failure, or any item cannot be collectively published, preserve the complete workspace and stop at the exact boundary, without falling back to selective commits.

Project Steward must enforce main file constraints during self-evolution:

Before writing, record the line count, character count, and direct reference set of SKILL.md, and assign a unique active owner to each new rule.
SKILL.md owns only routes, trigger conditions, reading order, permissions, output, and stopping points; complete methods, tables, checklists, and exceptions are uniquely owned by corresponding references, with the main file keeping only direct links.
After writing, SKILL.md must not exceed 220 lines or 14,000 characters, and all active capabilities must remain directly accessible. When a new route causes the budget to be exceeded, migrate or merge old details in the same change.
When existing capabilities, formal consumers, and verification cannot be retained within budget, stop writing and re-plan; do not declare completion.

Change Prevention

First read references/change-prevention.md, which is responsible for target behavior, single source of truth, impact graph, final interface, old path exit, and real user chain acceptance. Overlay based on the issue:

Bounded batches and backlog draining, recovery, restart, grouped artifacts for durable operations, queues, or schedulers, or concurrent admission, release, and shutdown for discoverable sessions and shared resources in persistent stateful services: references/durable-operation-governance.md
Task status, progress, or automatic re-runs: references/task-progress-governance.md
High-cost results requiring staged display, confirmation, continuous automatic execution, or invalidation on upstream changes: references/staged-result-governance.md
Same outcome expressed by multiple specs, plans, tasks, or research products with evolving relationships, or involving derived artifacts, semantic caching, work unit splitting, resource pool utilization, or duplicate agent orchestration: references/derived-artifact-governance.md
Project-level CI verification plan, execution environment caching, test resource tiering, time-consuming sharding, early failures, and precise re-runs: references/ci-execution-governance.md
Runtime configuration rebuilding shared services, providers, storage roots, or composition graphs: references/runtime-generation-governance.md
Hard-to-reproduce, timing, concurrency, backpressure, or expensive full chains: references/hard-to-reproduce-diagnostics.md
Multiple parsing, capacity, atomic sharding, replay cursors, or contract ambiguity in external, persisted, model, network, or process JSON: references/structured-data-boundary.md
Model involvement in task judgment, state expression, runtime events, or structured replies, requiring verification of message origin, role, routing, wire requests, and presentation responsibilities: references/model-mediated-operation-governance.md
External source code as a one-time starting point for an independent product, or selective adoption of its extension ecosystem: references/source-fork-and-ecosystem-adoption.md; when actually copying code, also read references/license-governance.md
Product experience or interfaces: references/product-experience-governance.md; when design or interaction methods are needed, also read references/ux-design.md

Only modify the project when the user explicitly authorizes implementation; if only a plan is requested, stop at the impact graph, target boundary, migration order, and acceptance contract.

Root Cause Remediation

First read references/root-cause-remediation.md. Diagnosis stops at evidence, impact scope, and final repair method; only during implementation migrate all producers, boundaries, and consumers at once, and exit the old architecture. Overlay based on the issue:

When fixing takes over a prior comprehensive audit from this task, or the user explicitly requires fixing all issues from that audit, the original audit handover ledger continues as the closing contract; before writing, fixedly read references/change-prevention.md, and after the last relevant modification, return to references/project-audit.md, regenerating the coverage and discovery ledger from the original scope and currently accepted contracts. A single-point defect does not expand to this chain merely because of an unrelated audit in history.

Bounded batches and backlog draining, recovery for durable operations, queues, or schedulers, or session admission and release contention in persistent stateful services: references/durable-operation-governance.md
Task progress or ongoing status: references/task-progress-governance.md
Rework from missing stage confirmation, drifted confirmation objects, or incorrectly propagated changes: references/staged-result-governance.md
Rework from unclear multi-artifact relationships, lost rationale on regeneration, full recalculation, incorrect cache invalidation, dangerous splitting, resource misjudgment, or orchestration roundtrips: references/derived-artifact-governance.md
Repeated slow tests, wasted environment preparation, imbalanced sharding, late cross-platform pre-checks, or undifferentiated retries on failure in project-level CI: references/ci-execution-governance.md
Runtime operations spanning service generations, hot configuration transactions, or physical root switches: references/runtime-generation-governance.md
Hard-to-reproduce or low observability issues: references/hard-to-reproduce-diagnostics.md
Encoding, resource budget, logical message capacity, atomic sharding, replay cursors, numerical values, schemas, or error semantic forks in structured JSON: references/structured-data-boundary.md
Model replies, task status, or result presentation inconsistent with real runtime, or needing to locate the actual request sent to the model: references/model-mediated-operation-governance.md
Visual hierarchy, transforms, or motion ownership: references/interaction-motion.md; when actual runtime screen verification is needed, also read references/implementation-review.md
Tools, path aliases, execution environment, or long-running tasks: references/user-environment-governance.md
Events, versions, history, or caches mistakenly treating planned impact as actual change facts: the "separation of planned scope from actual change facts" contract in references/change-prevention.md
Partial state, heartbeat, or telemetry updates overwriting or clearing undeclared fields, or consumers unable to distinguish between full snapshots and partial patches: the activity projection update contract in references/change-prevention.md
Source code, README, scripts, tests, or configurations hardcoding local or deployment facts: the project runtime configuration boundary in references/change-prevention.md; for user machine facts, also read references/user-environment-governance.md
Cohesion, coupling, semantic duplication, or god modules: references/architecture-cohesion-governance.md

External Tool Compatibility

Read references/external-tool-compatibility.md. When compatibility relationships involve cross-project-root public contracts, derived snapshots, or composite delivery packages, also read references/change-prevention.md's public contracts, contract adoption closure, and cross-root delivery boundaries. Compatibility checks remain read-only, reporting executable artifacts, capability contracts, invocation and isolation, temporary input, upstream wire protocols, structured results, host-independent verification, and user chain by explicit adapter layer; only modify approved project roots when explicitly authorized to fix or integrate.

Project Research and Explanation

First read references/project-research.md. Only read the project surface needed to answer the current question; when the user explicitly requests a full research or capability adoption, extend coverage and also read references/source-fork-and-ecosystem-adoption.md, first tracing the original upstream and distinguishing direct reuse from method learning; when confirming that code or resources will be directly reused, also read references/license-governance.md, writing third-party resources and attributions into the target project README. When needing to measure effectiveness, failure samples, and confidence, read references/project-effectiveness-review.md; when needing to save a verifiable report, read references/project-research-report.md. For source code archives, first use scripts/extract_project_archive.ps1 with -DestinationRoot to decompress into an independent directory; when no target root is specified, use E:\Work\BaiduSyncdisk\Code\Example. After the script returns the project root, immediately read references/archive-safety-screening.md and run scripts/inspect_extracted_project_safety.py; only enter user output when this method confirms significant hazards, otherwise silently continue the original research.

Repository Directory Governance

Read references/repository-directory-governance.md. First use scripts/inspect_project_tree.py to obtain read-only physical and Git evidence, then verify each candidate directory's formal producer, path source of truth, consumers, and lifecycle; stop at the evidence ledger for checks, explanations, and plans; only change exact paths when explicitly authorized to organize, move, or archive, and continue to respect separate authorization for deletions. When moving touches active source code, models, data, assets, build, or run entry points, also read references/change-prevention.md; when old paths, dual reads, synchronized copies, or partial migrations already exist, also read references/root-cause-remediation.md, migrating consumers at once and exiting old entry points.

Project Baseline and Templates

Read references/project-template-system.md. Read-only requests stop at inspect, plan, or verify; adopt, upgrade, or project configuration writes require explicit authorization and verification of formal consumers.

Template Evolution

Read references/template-evolution.md. First prove that the candidate is a stable default rather than a method still requiring on-the-spot judgment, then synchronize template versions, registries, hashes, documentation, and consumer tests.

Product Experience and Interface Governance

First read references/product-experience-governance.md, then execute according to the following fixed entry points and conditional specials:

Interface diagnosis, evaluation, optimization, or reconstruction: fixedly read references/ux-design.md, references/interface-experience-quality.md, references/interface-problem-patterns.md, references/implementation-review.md. Before modifying, first freeze all relevant windows, pages, panels, overlays, major states, and user journeys; do not treat the most prominent local issue in a screenshot as the complete review scope.
Designing from scratch or changing visual direction: references/design-method.md, references/visual-direction.md, references/surface-registers.md
Layout, design systems, interaction, and motion: references/layout-responsive.md, references/design-system-alignment.md, references/interface-guidelines.md, references/interaction-motion.md
Faithful reconstruction from a reference interface: references/reference-interface-reconstruction.md
When confirmed as desktop, Tauri/Vue, or local file workspace, correspondingly read references/desktop-app-governance.md, references/tauri-vue-governance.md, references/local-file-workspace-governance.md; when the project form is already established, do not omit the platform shell just because the current feedback only mentions colors, spacing, or copy.
Task status or progress: references/task-progress-governance.md

When relying on existing positioning or design systems, run scripts/context.mjs at most once per task; when faithfully reconstructing a reference interface, assets/reference-reconstruction/component-spec.md handles component specifications.

Repository Creation and Publication

Read references/repository-publication.md. Distinguish initialization, commit, remote creation, push, visibility, checks, and deployment; execute only the authorized stopping point for each step, and verify exact repository identity, index, branches, remote, and concurrent changes before and after state changes.

README and Homepage

First read references/readme-delivery.md, using a delivery ledger to check Git boundaries, README, body, visuals, multi-language, license, Star History, GitHub Topics, repository metadata, verification, and stopping points; read-only requests stop at the same ledger, only implement when explicitly requesting optimization, rewrite, or full handling. Then read references/content-architecture.md; for full optimization or when involving logos or hero, read references/visual-direction.md, first completing a code-first formal identity source investigation, then read references/project-native-hero.md and references/github-readme-canvas.md as needed. When needing multi-language, personal entry points, or repository status sections, read assets/readme-profile/profile.json, consumed by scripts/readme_header.py using real files, repository identity, license, and explicitly parsed project navigation. Full README optimization for existing public GitHub repositories treats Star History and Topics as default delivery items: Star History reads references/github-star-history.md and references/repository-publication.md, Topics are written and back-read via scripts/github_topics.py; unless the user explicitly opts out or the target objectively does not apply, a successful outcome missing either real consumer cannot complete the entire delivery. Select as needed:

SVG and hybrid visuals: references/svg-production.md, references/hybrid-svg-production.md
Motion: references/motion-production.md
Platform boundaries: references/platform-guidelines.md
Specialized diagnostics or integration for self-hosted Star History: references/github-star-history.md; when only asking about failure reasons or current status, remain read-only; during implementation, precisely commit and push calling repository changes, manually run workflows, then verify along the real chain of API, generator, output branch, raw SVG, and README consumers

README does not serve as a second active source of truth for internal governance rules; self-evolution only updates the README when changing public identity, reader paths, main entry points, or maintenance navigation. After completion, run scripts/audit_readme.py and verify on the actual rendering surface.

License Governance

First read references/license-governance.md. After the user confirms a specific plan, also read references/license-rollout.md and implement; read-only requests stop at content boundaries, third-party dependencies, and plan comparisons.

Humane Logging

Read references/log-audit-standard.md. Check production, context, storage, reading, and final viewing results along a real operation; do not substitute a single pretty example for the complete event chain.

User Environment Profile and Execution Environment

Read references/user-environment-governance.md. The profile schema is handled by assets/user-environment/profile.schema.json, and deterministic operations by scripts/user_environment_profile.py. Inspect, plan, verify, and resolve maintain corresponding read-only or consumption boundaries; apply --write requires explicit profile write authorization and does not automatically authorize installation, download, or system setting modifications.

Comprehensive Project Audit

Read references/project-audit.md. When the user asks about implementation plan completeness, first establish an item-by-item conformance ledger from the original plan; once authorized to fix, regenerate a completely new review from the original plan and currently accepted contracts, without reusing old completion marks or inferring plan scope from existing tests. For a full check, first establish a coverage ledger for all applicable dimensions according to the project form, then load the specialized items required by those dimensions; do not backfill review scope based solely on issues already found. A read-only audit does not automatically govern. When needing to evaluate user effectiveness, append references/project-effectiveness-review.md; when needing to check task experience, append references/task-experience-audit.md.

Platform Template Resources

When processing corresponding project types, read as needed:

Desktop application: references/desktop-app-governance.md
Tauri v2 + Vue: references/tauri-vue-governance.md
Local file workspace: references/local-file-workspace-governance.md

These resources are active methods and do not mean the project has adopted a template; only when explicitly adopted and read by a formal consumer does .project-steward/project.json constitute a project template state.

Output and Completion

Output should first give the conclusion, then explain scope, evidence, unknowns, and next actions. Analysis must not be written as if already implemented; structural checks must not be written as if real user chain is established; current task behavior checks must not be written as if independent cold start has been proven.

When an impact graph exists, it must at least include producers, transmission or storage boundaries, consumers, final user outcomes, single source of truth, old path exit conditions, and acceptance entry points. When involving multiple historical outcomes, report main reasons, success mechanisms, capability gaps, formal owners, and verification levels one by one.

Only report completion after active routes, corresponding methods, formal consumers, deterministic tests, and the real user chain approved for this round are all consistent.

Project Steward

What is Project Steward?

Ask in your favorite AI

Documentation