94 lines
4.5 KiB
Markdown
94 lines
4.5 KiB
Markdown
---
|
|
name: initial-setup
|
|
description: "Set up or customize a freshly cloned generic project template. Use when asked for initial setup, getting started, onboarding, creating project configuration, or replacing sample project values. Interview the user and configure task tracking for any project, including novels, research, events, and software, without assuming a language or platform."
|
|
---
|
|
|
|
# Initial Project Setup
|
|
|
|
Configure this clone for its actual project, not for the project that originally
|
|
supplied the template. This workflow is equally valid for a novel, research,
|
|
an event, or software.
|
|
|
|
## Inspect First
|
|
|
|
Read [the README](../../../README.md),
|
|
[project-config.json](../../../project-config.json),
|
|
[AGENTS.md](../../../AGENTS.md), and
|
|
[task frontmatter and details](../../../docs/tasks.md). Check Git status.
|
|
Preserve existing materials and uncommitted changes.
|
|
|
|
## Interview
|
|
|
|
Use the available user-question tool, one question at a time. Reuse answers
|
|
already given; do not ask again unnecessarily. Collect:
|
|
|
|
1. Project name.
|
|
2. A short description of its purpose, audience, and intended outcome.
|
|
3. Task ID prefix (recommend `EX` for an example; otherwise let the user choose).
|
|
Validate `[A-Za-z][A-Za-z0-9_-]*`; display IDs will be uppercase.
|
|
4. Whether there is one project category or several. Collect each label,
|
|
unique stable key, and repository-relative path (`.` for a single project).
|
|
5. How completed work should be verified. Ask about named commands only if
|
|
relevant. Do not assume tests, builds, a development server, a programming
|
|
language, or a target platform. Editorial review is a valid answer.
|
|
6. Whether to keep and adapt the sample task. Preserve real tasks unless the
|
|
user explicitly approves replacing them. Collect any desired task-type
|
|
changes; generic `task` and `chore` are sufficient for many projects.
|
|
|
|
Present a concise configuration summary and obtain confirmation before
|
|
replacing existing configuration or task content.
|
|
|
|
## Write the Configuration
|
|
|
|
Update `project-config.json` as valid JSON:
|
|
|
|
```json
|
|
{
|
|
"name": "Example Project",
|
|
"description": "Describe the project's purpose and intended outcome.",
|
|
"commands": {}
|
|
}
|
|
```
|
|
|
|
`name` and `description` must be non-empty strings. `commands` maps arbitrary
|
|
non-empty names to non-empty command strings. Leave it empty when no commands
|
|
are applicable. Record non-command acceptance/review criteria in AGENTS.md or
|
|
the task descriptions. Never store secrets or machine-specific absolute paths.
|
|
Commands are prompt guidance, not automatically run by the task-agent helpers.
|
|
|
|
Update task frontmatter with the agreed prefix and project categories.
|
|
Keep YAML in the flat format understood by the task parser: unindented scalar
|
|
fields, two-space list items, and four-space item fields. Do not introduce YAML
|
|
anchors, nested mappings, or multiline scalar values. Keep the existing
|
|
status lifecycle unless the user explicitly requests changes.
|
|
|
|
If renaming a project key, migrate matching task anchor `data-project`
|
|
attributes. Preserve task numbers, descriptions, checklists, epic/subproject
|
|
assignments, and existing internal links. Do not duplicate task configuration
|
|
in JSON. Update the README's project description and examples to match, keeping
|
|
Getting Started at the top. Update AGENTS.md only with confirmed project facts
|
|
and verification criteria; never invent an application architecture.
|
|
|
|
## Synchronize and Verify
|
|
|
|
If the optional CLI runtime is available:
|
|
|
|
1. Check whether `TASK_ID_PREFIX` or `TASKS_FILE` overrides the intended
|
|
configuration; explain conflicts rather than silently changing the result.
|
|
2. Run `./scripts/update-tasks -f docs/tasks.md`. This migrates IDs/internal
|
|
links and regenerates tables. Do not manually edit generated tables.
|
|
3. Run `./scripts/get-tasks --all -f docs/tasks.md` and query a task by number.
|
|
4. Run `python3 -m json.tool project-config.json` and
|
|
`python3 -m unittest discover -s scripts/tests -v`.
|
|
5. Verify the configured name, description, commands, project labels, and task
|
|
prefix persisted. Check for stale template identities and broken links.
|
|
6. Summarize changed files, verification results, and any remaining human review.
|
|
|
|
The tracker synchronizer currently requires at least one detailed task. Do
|
|
not remove the last task and claim synchronization succeeded; keep/adapt it or
|
|
ask how to handle an explicitly requested empty tracker.
|
|
|
|
If the runtime is unavailable, disclose that and offer either tool installation
|
|
or a manual Markdown workflow. Do not run application commands merely because
|
|
setup recorded them. Do not commit unless the user asks.
|