Repository navigation
Improve the README and record planned work - #12
Merged
Merged
Conversation
The README introduced the commands as pre-release and listed which of them had not been run against a live server. With 0.1.0 released, the commands are presented as the features they are, and only the defects that remain are kept, in "Known limitations". The anonymous-access limitation now states the behaviour instead of the lack of a test. CLAUDE.md and the html-quirks backlog entry drop the same account of what release 0.0.5 had and had not been checked against. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015w3YJNX9AzYUZq25WyQFDp
Referencing related work items is one of the success metrics in the project brief, yet the work item commands print fields only, and relations reach the output only through a WIQL link query. Exposing --expand together with rendering relations was deferred when the batch commands were added, but the decision was recorded only in the archived tasks file, so it is now kept as a backlog entry. It goes first: it completes the existing work item domain rather than opening a new one. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015w3YJNX9AzYUZq25WyQFDp
A new user had to read the whole README to get from download to a working agent. The quick start gives the five steps in order, each a single action, and leaves the details and variations to the existing sections, linked in one paragraph after the list. Setting a default project is left out: most users work with several projects, so it is a choice for later rather than a setup step, and the skill step names no particular agent, since any agent with skill support is served. The token scopes are now a list both here and under "Authentication", where a single scope in running text was easy to miss and further domains will add more. Writing the quick start showed that a server refusing a POST request for lack of an api-version gives the user no next step, since the hint about the version settings is added only when a version is configured; the fix is recorded as TASK-08 in the first-run errors tasks file. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015w3YJNX9AzYUZq25WyQFDp
The sections now follow the order of the quick start: installation, authentication, the agent skill, then configuration and usage. Known limitations move to the end, so that a new reader meets the setup before the defects, and the feature list links to them. The paragraph on auth login mixed what the command does with internal details and fixes for particular setups; it is split into the behaviour and a list of those setups, and the request path and the URL normalisation, recorded in the project brief, are left out. The api-version paragraph becomes a subsection that says what happens by default, when a version is needed, and how to choose one, with the server-to-version mapping as a table. Configuration opens with a single table of every setting, the TLS keys included, so that everything that can be set is visible in one place. A full example config was considered and rejected: JSON cannot mark a key as optional, and a copied apiVersion or insecureSkipVerify would pin a version or disable certificate checks without the user deciding to. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015w3YJNX9AzYUZq25WyQFDp
Without a configured API version, get-batch and query-by-wiql fail on servers that refuse a POST request without one, and neither the user nor an agent can be expected to know the right value. The official SDKs settle this by asking the server with OPTIONS on _apis; the entry records the decision to do the same for every request, sending the version the server itself would choose, and falling back to the current behaviour whenever negotiation fails, so that no server that works today stops working. It goes first: two of the four commands are affected, whereas the work item relations of the next entry can already be reached through WIQL. The project brief, CLAUDE.md, and the README change together with the implementation rather than now. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015w3YJNX9AzYUZq25WyQFDp
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation and planning changes only; no code changes.
CLAUDE.mdand thehtml-quirksbacklog entry drop the same account.auth login, check with oneget, copy the skill. Details stay in the existing sections, linked after the list. Token scopes are a list here and under "Authentication", so that later domains can add to them.auth loginparagraph is split into what the command does and a list of particular setups (URL copied from the browser, internal CA, Git Bash, CI). The API version section gets the server-to-version mapping as a table. "Configuration" opens with one table of every setting, TLS keys included. A full example config was considered and rejected: JSON cannot mark a key as optional, and a copiedapiVersionorinsecureSkipVerifywould pin a version or disable certificate checks without anyone deciding to.api-version-negotiation, first. Without a configured version,get-batchandquery-by-wiqlfail on servers that refuse a POST request without one. The entry records the decision to negotiate the version withOPTIONS {collection}/_apis, as the official SDKs do. When negotiation fails, the request goes out without a version as before, so no server that works today stops working. The project brief,CLAUDE.md, and the README change together with the implementation.workitem-relations. Exposing--expandtogether with rendering relations was deferred when the batch commands were added, but the decision lived only in an archived tasks file.api-version. It will move into the negotiation work when that starts.