Download track

.myteam/asking-questions/load.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+from pathlib import Path
+
+from myteam.utils import get_active_myteam_root, list_roles, list_skills, list_tools, print_instructions
+
+
+def main() -> int:
+    base = Path(__file__).resolve().parent  # .myteam/<role>
+    print_instructions(base)
+    myteam = get_active_myteam_root(base)
+    list_roles(base, myteam, [])
+    list_skills(base, myteam, [])
+    list_tools(base, myteam, [])
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.myteam/asking-questions/skill.md

@@ -0,0 +1,22 @@
+---
+name: Asking Questions
+description: |
+  This skill described the process to follow when asking the user questions.
+  If you will ask the user questions in any way, load this skill first. 
+---
+
+## Asking Questions
+
+When asking questions, always ask the questions one-at-a-time. 
+
+List out the questions you want to ask in a plan.
+
+Then go through that plan one question at a time.
+This lets the user discuss the question before providing an answer.
+
+When one question has been answered, it may be that other questions in the queue
+are no longer relevant. Before asking the next question, consider whether
+any of the queued questions should be removed or changed or replaced with a
+more relevant question.
+
+When all your questions are answered, continue.

.myteam/feature-pipeline/framework-oriented-design/skill.md

@@ -13,6 +13,9 @@ An application is a combination of framework and business logic.
 
 We seek to separate framework code for business logic code.
 
+*Framework* refers to the internal, helper code that supports the primary API of the application,
+as well as the conventions and patterns used in the codebase to create consistency and structure.
+
 When preparing to implement a feature, understand the existing framework:
 
 - Why was the code written the way it does? What problems does the current design solve?
@@ -26,9 +29,9 @@ followed by a change to the business logic.
 
 If a change to the framework is needed, refactor the code accordingly without adding
 any new behavior. 
+
 Guidance:
 
-- 
 - Review the principles of self-documenting code and follow them.
 - Functions should be simple, focused, and easy to read.
 - When creating helper functions, look for existing behavior.

.myteam/feature-pipeline/skill.md

@@ -7,73 +7,108 @@ description: |
 
 ## Feature Pipeline
 
-Carefully follow each of these steps in order. 
-Create a plan that has checkboxes for each of these steps.
-
-When using the term "feature", we mean any change to the code or assets,
-not just new additions to the codebase.
+Carefully follow each of these steps in order. Do not proceed to a later step until the earlier step is finished.
+We're not worried about multitasking and efficiency; we care about process and quality.
 
 ### Create the git branch
 
 Check the current branch. 
-If you are on `main`, create a new branch for the feature.
-The branch name should be simple but descriptive.
+If you are on `main`, remind the user to start a new branch and wait for them to do so before proceeding.
 
-If you are on a different branch (not `main`), 
-confirm with the user whether this branch should be used for the feature,
-or whether a new branch should be created.
+### Understand the feature and update the interface document
 
-If the user's description of the feature is too vague
-to name the branch, get enough details to select a reasonable name.
+The goal of this step is to thoroughly understand the requested feature
+and document how the primary interface of the application should be changed.
 
-The name does NOT need to be perfect; as long as it 
-is loosely relevant, it will work great.
+First read `src/governing_docs/application_interface.md` to understand
+the current design and intent of the project.
+This document describes what this app should do, how it behaves, etc.
+It is the black-box description of the user's experience with the application.
 
-### Plan the feature
+Then seek to understand what the user wants to change. 
+Is it a new behavior? Modifying an existing behavior? A bugfix?
 
-The goal of this step is to thoroughly understand the requested feature.
+Discuss these things with the user. Involve them in the process.
 
 Questions that might be relevant:
 
-- What change in behavior does the user hope for?
-  - What behaviors should NOT change?
-- How might this change be implemented?
-  - If there are multiple reasonable strategies, what distinguishes them?
-  - Are there dependencies that may change? 
-  - Is there documentation via skills or in the repo that suggests a strategy?
-  - Does the user have an opinion on which strategy is used?
+- What changes in behavior does the user hope for?
+- What behaviors should NOT change?
 
-Prepare a document in `src/governing_docs/feature_plans/<branch_name>.md`
-that describes the specific details and strategies decided on for the feature.
+Once you have a thorough understanding of the user's intent, 
+update the `application_interface.md` document to reflect the changes.
 
-Get approval from the user on this document before continuing.
+Review these changes with the user. Make sure you are both on the same page
+before you continue.
 
 When this step is complete, commit your changes before moving on.
 
-### Update the interface document
+### Design the feature
 
-`src/governing_docs/application_interface.md` describes 
-what this app should do, how it behaves, etc.
-It is the black-box description of the user's experience with the application.
+The goal of this step is to understand how the feature will be implemented.
+It is NOT to implement that changes. That will come later.
 
-Based on the details in the feature plan document, determine how the 
-user interface of the application will change.
+#### Understand the context
 
-Update the `application_interface.md` document to reflect the new feature.
+Load the `framework-oriented-design` skill. 
 
-Review these changes with the user. Make sure you are both on the same page
-before you continue.
+Then look through the code. Understand the framework and infrastructure in place that supports the current application.
+Notice the intentional design decisions and articulate the reasoning for those decisions.
+
+#### Plan the feature
+
+Now, consider how this feature could be implemented. 
+
+Is the existing framework sufficient to support this new feature?
+If not, how should the framework be modified to naturally support the feature?
+
+Implementing a feature has two phases: 1) updating the framework, and 2) sliding the new feature into place.
+If the framework is right, the new feature will be simple to implement. 
+So, make sure we understand how the framework is going to change to accommodate the feature.
+
+Think through how the framework changes will make the feature implementation simple. 
+As necessary, iterate on this process until you have a simple refactor that supports a simple feature implementation. 
+
+If changes to the framework are needed, consider: 
+
+- If there are multiple reasonable strategies, what distinguishes them?
+- Are there dependencies that may change? 
+- Is there documentation via skills or in the repo that suggests a strategy?
+- Does the user have an opinion on which strategy is used?
+
+Be specific. This is the stage of the process where you figure out all the details.
+Do not leave any decisions for later. 
+
+Think critically about the changes. Is there a simpler way? 
+Simplicity is SO important to maintaining a codebase. Be very skeptical of new complexity.
+
+Think also about consistency. Is there a style or pattern already used in the codebase that could be followed?
+
+Prepare a document named `src/governing_docs/feature_plans/<branch_name>.md`
+that describes the specific details and strategies decided on for the feature.
+
+This document should have two main parts:
+
+1) Framework refactor: here describe the feature-neutral refactorings to the existing code that prepare the code for the new feature
+   - The existing test suite should not need to change in response to this step
+   - If changes are needed because the framework has changed, and thus the testing infrastructure must be modified, that's fine
+2) Feature addition: here describe the code needed to introduce the new feature 
+
+Get approval from the user on this document before continuing.
 
 When this step is complete, commit your changes before moving on.
 
 ### Refactor the framework
 
-Load the `framework-oriented-design` skill.
-
-Following its guidance, make any necessary changes to the application framework.
+Following the feature plan part 1 guidance, make any necessary changes to the application framework.
 
 The existing tests should all still pass.
 
+Describe to the user the changes that were made and why they were made. 
+Explain how these changes will make adding the feature a simple process.
+
+Get approval from the user on these changes before continuing.
+
 When this step is complete, commit your changes before moving on.
 
 ### Update the test suite
@@ -88,15 +123,24 @@ Make these changes to the test suite.
 Review the changes one more time: do they faithfully capture the new interface design?
 Make changes as needed.
 
+Explain to the user how the new tests address the changes made to the interface document.
+Get their approval before continuing.
+
 When this step is complete, commit your changes before moving on.
 
 ### Implement the feature
 
-Now that the framework has been updated (if necessary) and the tests are in place,
+Now that the framework has been updated (as necessary) and the tests are in place,
 implement the feature.
 
+Follow the guidance in part 2 of the feature document.
+
+Use the existing framework to support the feature. 
+
 The tests should pass. 
 
+Review the changes made with the user. Get their approval before continuing.
+
 When this step is complete, commit your changes before moving on.
 
 ### Concluding the feature

.myteam/role.md

@@ -7,3 +7,4 @@ If there is a skill that sounds like it might apply,
 you MUST load it.
 DO NOT assume ANYTHING is simple enough to justify ignoring a skill or role.
 
+According to the request of the user, load the appropriate skill and proceed.

.myteam/testing/skill.md

@@ -28,3 +28,4 @@ uv run pytest
 
 Tests are found in `tests/`.
 
+The full test suite takes about 30 seconds to run. Plan accordingly. 

README.md

@@ -270,7 +270,21 @@ Lists available downloadable rosters from the default roster repository.
 
 ### `myteam download <roster>`
 
-Downloads a roster into `.myteam/` by default.
+Downloads a folder roster into `.myteam/` by default.
+
+By default, the roster path is preserved under `.myteam/`, so `myteam download skills/foo` installs
+into `.myteam/skills/foo/`. If you provide a destination path, that path becomes the managed install
+root under `.myteam/`.
+
+Each downloaded folder gets a `.source.yml` file at its root so future commands can track where it
+came from.
+
+If the destination already exists, `myteam download` fails instead of merging into it:
+
+- if the existing folder is the same managed source, run `myteam update <path>` instead
+- if the existing folder is unrelated content, delete it or choose a different destination
+
+Single-file roster downloads are not supported.
 
 Useful when you want to seed an agent system from a reusable template instead of authoring it from scratch.
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "myteam"
-version = "0.2.6"
+version = "0.2.7"
 description = "Agent roster CLI"
 readme = "README.md"
 requires-python = ">=3.11"

src/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Change Log
 
+## 0.2.7
+
+- `myteam download` now installs only folder rosters as managed local folders instead of flattening
+  roster contents directly into the destination root.
+- Default downloads preserve the remote roster path under `.myteam/`, and explicit destinations are
+  treated as managed install roots under `.myteam/`.
+- Managed roster installs now write `.source.yml` at the folder root so future commands can track
+  their origin.
+- `myteam download` now fails when the target already exists, directing same-source reinstalls toward
+  `myteam update <path>` and rejecting unrelated existing content.
+- Removed support for single-file roster downloads.
+
 ## 0.2.6
 
 - `myteam init` now stores the creating `myteam` version in `.myteam/.myteam-version`.

src/governing_docs/application_interface.md

@@ -222,27 +222,38 @@ Failure conditions that matter at the interface:
 
 ### `myteam download <roster>`
 
-Downloads a named roster from a remote repository.
+Downloads a named roster folder from a remote repository as a managed local install.
 
 Inputs:
 
-- `<roster>` identifies the roster entry to download.
+- `<roster>` identifies the remote roster folder to download.
 - The command also supports an optional destination and alternate repository through its CLI wiring.
+- If no destination is provided, the roster path is installed under `.myteam/` using the same relative
+  folder path as the remote roster.
 
 Expected outcome on success:
 
-- Downloads the requested roster content from the configured repository.
-- Writes the downloaded files into `.myteam/` by default.
-- Creates destination directories as needed.
+- Downloads the requested roster folder content from the configured repository.
+- Creates one managed local folder for that install.
+- Writes a `.source.yml` provenance file at the root of the managed local folder.
+- Writes downloaded files inside that managed local folder while preserving their relative paths within
+  the roster.
 - Prints progress while downloading.
 
 User-visible result:
 
-- The downloaded roster becomes available on disk in the destination directory, ready to be loaded or edited.
+- The downloaded roster becomes available on disk as a managed folder, ready to be loaded or edited.
+- The managed folder records enough source information for later provenance-aware commands.
 
 Failure conditions that matter at the interface:
 
 - If the roster name does not exist in the repository, the command exits with an error and reports available roster names.
+- If the requested roster resolves to a single file instead of a folder, the command exits with an error.
+- If the destination already contains the same managed source, the command exits with an error that
+  tells the caller to run `myteam update <path>` instead of using `download` again.
+- If unrelated content already exists at the destination path, the command exits with an error that
+  explains the content is not the same managed source and tells the caller to delete it or choose a
+  different destination instead of merging.
 - If the remote metadata or file downloads fail, the command exits with an error.
 
 ### `myteam --version`