feat: post init config command

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,7 +7,7 @@
 <!-- How did you test your changes? -->
 
 - [ ] Tested locally with `uv run specify --help`
-- [ ] Ran existing tests with `uv sync && uv run pytest`
+- [ ] Ran existing tests with `uv sync --extra test && uv run pytest`
 - [ ] Tested with a sample project (if applicable)
 
 ## AI Disclosure

AGENTS.md

@@ -540,6 +540,10 @@ Disclosure is **continuous**, not a one-time event. A single AI-disclosure parag
 
 ## Common Pitfalls
 
+For local Ruff checks, use the CI-pinned `uvx` command in
+[Run Lint / Basic Checks](docs/local-development.md#8-run-lint--basic-checks),
+even when Ruff is absent from `PATH` and `.venv`.
+
 1. **Using shorthand keys for CLI-based integrations**: For CLI-based integrations (`requires_cli: True`), the `key` must match the executable name (e.g., `"cursor-agent"` not `"cursor"`). `shutil.which(key)` is used for CLI tool checks — mismatches require special-case mappings. IDE-based integrations (`requires_cli: False`) are not subject to this constraint.
 2. **Reintroducing context handling into the CLI**: The opt-in `agent-context` extension owns everything about context files — including the per-agent default mapping in `agent-context-defaults.json`. Integration classes must **not** declare a `context_file`, and no CLI code should read, write, resolve, or migrate context files. All context-file logic lives in `.specify/extensions/agent-context/` and its bundled scripts.
 3. **Incorrect `requires_cli` value**: Set to `True` only for agents that have a CLI tool; set to `False` for IDE-based agents.

CONTRIBUTING.md

@@ -226,6 +226,10 @@ job until a follow-up cleanup tightens the threshold.
 
 ### Manual testing
 
+This section covers testing slash-command behavior through a coding agent and
+reporting those results in a pull request. For post-initialization configuration,
+run the automated verifier in the [local development guide](docs/local-development.md#4-verify-post-initialization-configuration).
+
 #### Testing setup
 
 ```bash
@@ -257,21 +261,21 @@ Any change that affects a slash command's behavior requires manually testing tha
 
 Paste this into your PR:
 
-~~~markdown
+```markdown
 ## Manual test results
 
 **Agent**: [e.g., GitHub Copilot in VS Code]  |  **OS/Shell**: [e.g., macOS/zsh]
 
 | Command tested | Notes |
 |----------------|-------|
 | `/speckit.command` | |
-~~~
+```
 
 #### Determining which tests to run
 
 Copy this prompt into your agent. Include the agent's response (selected tests plus a brief explanation of the mapping) in your PR.
 
-~~~text
+```text
 Read CONTRIBUTING.md, then run `git diff --name-only main` to get my changed files.
 For each changed file, determine which slash commands it affects by reading
 the command templates in templates/commands/ to understand what each command
@@ -303,7 +307,7 @@ Number each test sequentially (T1, T2, ...). List prerequisite tests first.
 
 - T1: /speckit.command — (reason)
 - T2: /speckit.command — (reason)
-~~~
+```
 
 ## AI contributions in Spec Kit
 

docs/local-development.md

@@ -47,7 +47,25 @@ specify --help
 
 Re-running after code edits requires no reinstall because of editable mode.
 
-## 4. Invoke with uvx Directly From Git (Current Branch)
+## 4. Verify Post-Initialization Configuration
+
+Use the automated verifier to exercise the post-initialization configuration
+workflow in a disposable Copilot project. After completing the editable install
+in the previous section, run:
+
+```bash
+scripts/dev/verify-post-initialization-configuration.sh --specify "$(pwd)/.venv/bin/specify"
+```
+
+The script verifies configuration reads, script upgrades, mutable settings,
+persisted options, protected settings, and the bundled `git` extension
+lifecycle. It removes the temporary project when it exits. Set `SPECIFY` to an
+executable path instead of passing `--specify` if preferred.
+
+For manual slash-command testing and its pull-request reporting template, see
+[Manual testing](../CONTRIBUTING.md#manual-testing).
+
+## 5. Invoke with uvx Directly From Git (Current Branch)
 
 `uvx` can run from a local path (or a Git ref) to simulate user flows:
 
@@ -63,7 +81,7 @@ git push origin your-feature-branch
 uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch specify init demo-branch-test --script ps
 ```
 
-### 4a. Absolute Path uvx (Run From Anywhere)
+### 5a. Absolute Path uvx (Run From Anywhere)
 
 If you're in another directory, use an absolute path instead of `.`:
 
@@ -87,7 +105,7 @@ specify-dev() { uvx --from /mnt/c/GitHub/spec-kit specify "$@"; }
 specify-dev --help
 ```
 
-## 5. Testing Script Permission Logic
+## 6. Testing Script Permission Logic
 
 After running an `init`, check that shell scripts are executable on POSIX systems:
 
@@ -98,7 +116,7 @@ ls -l scripts | grep .sh
 
 On Windows you will instead use the `.ps1` scripts (no chmod needed).
 
-## 6. Scaffold a Built-In Integration
+## 7. Scaffold a Built-In Integration
 
 Use the integration scaffold command to create the initial Python package and
 test skeleton for a new built-in integration:
@@ -118,21 +136,28 @@ The scaffold does not register the integration automatically. Review the
 generated metadata, then add the import and `_register()` call in
 `src/specify_cli/integrations/__init__.py`.
 
-## 7. Run Lint / Basic Checks
+## 8. Run Lint / Basic Checks
 
-CI enforces `ruff check src tests` (see `.github/workflows/test.yml`), so run it locally before pushing:
+Run Ruff from the repository root through `uvx`, matching the version pinned in
+`.github/workflows/test.yml`:
 
 ```bash
-uvx ruff check src tests
+uvx ruff@0.15.0 check src tests
 ```
 
+Ruff does not need to be on `PATH` or installed in `.venv`; `uvx` manages its
+isolated tool environment. Do not report Ruff unavailable just because those
+locations lack the executable. If the tool is already cached, use
+`uvx --offline ruff@0.15.0 check src tests` to run without network access.
+If sandbox permissions block the uv cache, request cache access and retry.
+
 You can also quickly sanity check importability:
 
 ```bash
 python -c "import specify_cli; print('Import OK')"
 ```
 
-## 8. Build a Wheel Locally (Optional)
+## 9. Build a Wheel Locally (Optional)
 
 Validate packaging before publishing:
 
@@ -143,7 +168,7 @@ ls dist/
 
 Install the built artifact into a fresh throwaway environment if needed.
 
-## 9. Using a Temporary Workspace
+## 10. Using a Temporary Workspace
 
 When testing `init --here` in a dirty directory, create a temp workspace:
 
@@ -154,7 +179,7 @@ python -m src.specify_cli init --here --integration claude --ignore-agent-tools
 
 Or copy only the modified CLI portion if you want a lighter sandbox.
 
-## 10. Debug Network / TLS Issues
+## 11. Debug Network / TLS Issues
 
 > **Deprecated:** The `--skip-tls` flag is a no-op and has no effect.
 > It was previously used to bypass TLS validation during local testing.
@@ -163,7 +188,7 @@ Or copy only the modified CLI portion if you want a lighter sandbox.
 >
 > For example, set `SSL_CERT_FILE` or configure `HTTPS_PROXY` / `HTTP_PROXY`.
 
-## 11. Rapid Edit Loop Summary
+## 12. Rapid Edit Loop Summary
 
 | Action | Command |
 |--------|---------|
@@ -174,15 +199,15 @@ Or copy only the modified CLI portion if you want a lighter sandbox.
 | Git branch uvx | `uvx --from git+URL@branch specify ...` |
 | Build wheel | `uv build` |
 
-## 12. Cleaning Up
+## 13. Cleaning Up
 
 Remove build artifacts / virtual env quickly:
 
 ```bash
 rm -rf .venv dist build *.egg-info
 ```
 
-## 13. Common Issues
+## 14. Common Issues
 
 | Symptom | Fix |
 |---------|-----|
@@ -192,7 +217,7 @@ rm -rf .venv dist build *.egg-info
 | Wrong script type downloaded | Pass `--script sh`, `--script ps`, or `--script py` explicitly |
 | TLS errors on corporate network | Configure your environment's certificate store or proxy. The `--skip-tls` flag is deprecated and has no effect. |
 
-## 14. Next Steps
+## 15. Next Steps
 
 - Update docs and run through Quick Start using your modified CLI
 - Open a PR when satisfied

docs/reference/configuration.md

@@ -0,0 +1,72 @@
+# Project Configuration
+
+Use `specify config` to inspect and safely change supported settings recorded
+when you initialized a project. Run these commands from the project root, or
+set `SPECIFY_INIT_DIR` to the project root.
+
+## Inspect configuration
+
+```bash
+specify config list
+specify config list --json
+specify config get script
+```
+
+`list` shows persisted initialization settings and a summary of installed
+extensions. `--json` prints both as machine-readable JSON.
+
+## Change supported initialization settings
+
+```bash
+specify config set feature-numbering timestamp
+```
+
+Supported values are:
+
+| Setting | Values |
+| --- | --- |
+| `feature-numbering` | `sequential`, `timestamp` |
+
+Legacy projects without `.specify/init-options.json` must first run
+`specify integration install <key>` (or `specify integration use <key>` for an
+already installed integration). Until then, `config set` refuses to create the
+file because doing so without an active agent would disable legacy extension
+and preset command registration.
+
+Script type, the active integration, and skills layout are owned by
+`specify integration`. Changing a script type requires regenerating installed
+agent files:
+
+```bash
+specify integration upgrade <integration> --script py
+```
+
+Use the active integration key to update both its commands and the script
+setting shown by `config get script`. Supported script types are `sh`, `ps`,
+and `py`. Upgrade checks manifest hashes and refuses to overwrite modified
+files without `--force`; review those changes before choosing to overwrite
+them.
+
+Use `specify integration use <integration>` to select an installed integration.
+For layout changes, use `specify integration upgrade <integration>
+--integration-options="..."` with that integration's supported options. For
+example, Copilot supports `--integration-options="--commands"`. Layout options
+vary by integration; `ai-skills` is not a universal toggle.
+
+`here` and `speckit-version` are read-only initialization metadata. Known
+read-only settings and unknown keys produce distinct errors when set.
+
+## Manage extensions
+
+`specify config extension` exposes the existing extension lifecycle under the
+configuration namespace. It has the same behavior as `specify extension`.
+
+```bash
+specify config extension list
+specify config extension add tdd
+specify config extension disable tdd
+specify config extension enable tdd
+specify config extension remove tdd
+```
+
+Use `specify config extension --help` to see the full extension command set.

docs/reference/overview.md

@@ -8,6 +8,14 @@ The foundational commands for creating and managing Spec Kit projects. Initializ
 
 [Core Commands reference →](core.md)
 
+## Project Configuration
+
+Project configuration lets you inspect settings recorded during initialization,
+change supported settings, and access extension lifecycle commands from the
+same configuration namespace.
+
+[Project Configuration reference →](configuration.md)
+
 ## Integrations
 
 Integrations connect Spec Kit to your AI coding agent. Each integration sets up the appropriate command files and directory structures for a specific agent. Only one integration is active per project at a time, and you can switch between them at any point.

docs/toc.yml

@@ -35,6 +35,8 @@
       href: reference/overview.md
     - name: Core Commands
       href: reference/core.md
+    - name: Project Configuration
+      href: reference/configuration.md
     - name: Integrations
       href: reference/integrations.md
     - name: Extensions